System Attribute

From Planimate Knowledge Base
Revision as of 00:22, 13 December 2008 by Tony.Griffith (talk | contribs)
Jump to navigation Jump to search

System Attributes

System Attributes are where Planimate® manages various attributes to run the model.

These attributes (e.g. the clock time), may be referenced. In some cases they may be set by the modeller in a Routine.


Uses for System Attributes

System Attributes are always available.

You can derive information about time spent in various states or regions of the model.

They give access to time variables useful in developing or monitoring schedules of activity.

Time-Related System Attributes

These attributes cover pretty much all there is to know about both simulation time (i.e. within the Model during a run), and real time (i.e. the time at which you are running your model).

For full details refer to this page: Time-Related System Attributes

Item Related System Attributes

Each individual Item created in your model records and stores information about itself. This information can be useful to support identification and perhaps logging of each item's experience while it is the model.

For full details refer to this page: Item Related System Attributes

Item Animation Related System Attributes

These attributes are intended for run time assignment so their settings are not currently saved with the model and in fact cannot be edited directly, only via a routine calculation.

Name Read / Write Description

Item X Scale Item Y Scale R/W These enable an item's image to be scaled in the x and y direction. They are specified as a percentage, normally 100.

Item Image X StepItem Image Y Step R/W These control how stepping through images is performed (for multi-icon items) If X step is non zero, the x co-ordinate divided by the value is used to index an image, the default of 8 changes the image every 8 screen pixels. Likewise for Y (by default this is 0)

Item Image Time Step (ms) R/W The Time Step value uses the system real time clock to step images at a specified time interval (20ms is a good start) so the image will change at a regular interval no matter how fast the item is moving. Note: Time stepping cannot be used to animate items or objects which are not actually moving. Yet.


Owning Portal Object Related System Attributes

These system attributes enable a subsystem to access its owning portals graphics without having to use a label list

Name Read / Write Description

Current Screen Status R/W This is the Current State Value of the Portal Object above the subsystem in which this attribute is set or read. In this case, this Portal does not have to be part of the _Model Objects List, but it has to have its States customized.

Owning Portal Location R Returns you the index of the first portal above you in the hierarchy that is part of the _Model Objects system Label List (i.e. that has been exported).

Current Portal X/Y R/W Setting these attributes will move a Portal into a new position. There are other mechanisms to do this kind of repositioning also, which may be more appropriate. To make use of this attribute, you have to be inside the actual portal itself. Usually you will message or broadcast into the portal to get it move. Its main usefulness is that you can move a portal without having to export its identity into the _Model Objects label list.

Current Portal Width & Height R/W Setting these attributes will tell you the current size of the Portal.

Current Portal X Scale, Current Portal Y Scale R/W These enable a Portal’s image to be scaled in the x and y direction. They are specified as a percentage, normally 100. Be wary of large values, you will run out of memory and probably kill win95.


System String Related System Attributes

These system attributes provide information to assist with File input and output and management.

Name Read / Write Description


ModelName

R

Numerically these return zero but if referenced in a form field OR using the new "Format Into Label" routine operation, the names can be made accessible to the modeller for display.


ScenarioName

R

Numerically these return zero but if referenced in a form field OR using the new "Format Into Label" routine operation, the names can be made accessible to the modeller for display.


DatasetFileAndPath

R

This returns the path and filename of the last loaded/saved dataset1 "scenario", where the file browser was integrated into the scenario load process.

Modellers can also explicitly set it using routine operation "SetLastDataFile".

HINT: The "Include Scenario Name In Titlebar" system option shows the filename component of this in the titlebar of an application, useful in an application to remind users which data they have loaded.


LastAccessedDataFile

R

Stores last file read/written at change object.


LastAccessedDataFilePath

R

Stores the path to the last file read/written at change object.


LastLockFileError

R

If the lock is successful, the error result target is set to 0, otherwise a non zero error code (see below) is set. If an error occurs, detail of this error is available as a string in this system attribute. If the error is that another user has the lock, then this attribute will contain the "tag" and should be displayed to the user.


LocalComputerName

R

Provides the Network Name of the Computer the Model is being run on.

Model Run Engine Related System Attributes

These system attributes provide information to assist you in how to respond to activities and events in the Model during a Run.

Name

Read / Write

Description


RunNumber

R

Is the number that is appended to the Log files produced by Planimate®.


MultipleRunCount

R

is 0 for normal runs is the # of multiple runs for a multiple-run session


ContinueRun

R/W

Sets continue mode so a user event broadcast (eg: portal click) can continue the run. Equivalent to the user button "continue" option.


RoutineInLookahead

R

Reading this allows a Routine to control the flow of operations based on whether the execution of the routine is happening during a Lookahead as opposed to a Move. Useful when calling DLL’s.

This will also be set for messages sent from a routine in lookahead.

DoingTrackCheckNext

R

By testing this system attribute the modeller can give a controlled response to the CheckNext tests that the track network propagates. Using this flag a modeller can tell the track system whether a portal is safe to consider moving towards, even if the train is some distance back and not directly "TestEntering".


HandlingBroadcastOnly

R

Set to non zero if the current run is being performed as result of a broadcast without initialisation. This enables a model to catch when a broadcast button has been clicked *during* a run vs. when clicking it initiates the run.


HaveCurrentPendingEvents

R

Returns true if the FEC has any events scheduled to occur at exactly the current time - meaning that there is some unfinished activity at the current epoch which has not yet occurred - either because the user has paused the model or as a side effect of activity in the current thread (eg: unblocking). This is intended to enable modellers to check whether other 0-time activity is in progress when a new broadcast is initiated by the user interacting with the model. The modeller may want to prevent this second broadcast from proceeding in such circumstances.


LastRunStopReason

R

This returns a numeric code describing why the run/engine stopped LAST time. This can be very useful in handling error recovery and may make handling "just loaded" situations easier than using the "_model loaded" broadcast (but that BC is still available). Also very useful in handling restart dispatchers since the model can easily know that a "control" item will be present. The current codes are as follows: 0 Loaded/No Previous Run no previous run, model just loaded or created 1 User Stopped Run user selected stop from menu/keyboard 2 Model Stopped Run model self stopped (exit, posted stop message) 3 Platform Required platform stopped run (closing, load/save model/scenario, editing time ref) 4 Error In Model/Engine error in model or runtime engine 5 Broadcast Option broadcast set to stop 6 UI/Portal Click Option user interaction: portal clicks, 7 Restart Dispatcher restart dispatcher restarted the run (item preserved) A label list names these codes.


RandomSeedOnRestart

R/W

This enables the initial random seed for the NEXT run to be set when a run restart dispatcher is used. It also enables the random seed for the current run (single or multiple) to be read (unless the modeller has set it prior to a run/restart). Note: its OK to use incrementing seeds, internally Planimate® scrambles the initial seed to ensure the streams for the successive runs don’t trivially correlate. The seed value must be an integer between 1 and 32767 (inclusive) and a hard clamp has been introduced to ensure this.


RandomSeedImmediate

R/W

Enables reinitialisation of random seed without having to restart the engine.


ActiveBroadcastIndex

R

Run Engine system attribute returns label index of the currently active broadcast or 0 if none active.


RealTimeTickEnable

R/W

Run Engine System Attribute to control fine timer tick option on/off.


AnimationStartingMessage

R/W

Gives the modeller access to the option for whether "Animation Starting" messages will be presented to the user.



AutomaticRestartAfterError

R/W

This is an Experimental Feature

If the model sets this attribute to 1 during a run AND the "Restart When Model Stops" option is enabled, then PL will attempt to restart the model if a model error occurs.

This is intended for special cases where model errors in some runs are unavoidable (eg: a modeller managing multiple runs of a network directly rather than using PL's inbuilt mechanism).

It is not to be used for general modelling or catching file errors.
It will not work if the "Friendly Errors" dialog is enabled or any other dialog appears, apart from the standard "model error" dialog appears.

When an error occurs, the model error dialog appears for 10 seconds. If the user clicks/closes the dialog then the restart will not occur, otherwise the dialog closes and the model restarts.

The modeller should check and act on the "last stop reason" system attribute (if they are relying on restarts a handler for this should already be there).

Upon a restart this attribute gets reset to 0.

The modeller should only set it non zero after the code that proceeds it has been proven robust.


ModelNeedsSaving

R

The modeller can set/reset this to control whether PL will prompt to save the model upon exit.

This is only useful for models used by editors, obviously a standalone EXE isn't going to be saving any models.


UserMode

R/W

This is set non zero if the editing tools are unavailable (ie: the system is in user mode or a standalone EXE).

This enables a model to adapt its UI/operation for a developer or an end user


DisableUndo

R/W

s.DisableUndo (Run Engine) enables the modeller to disable the undo/revert mechanism that normally occurs when a routine is executed during lookahead (before the item actually moves).

Setting this non zero will cause attributes and tables altered during lookahead to retain whatever is done to them after the lookahead is complete.

The modeller must set this value back to zero before the routine finishes or an error will be reported.

This is intended for advanced users who are hooking into Planimate's lookahead mechanism, for example in routing trains.
Attributes modified while DisableUndo is set do not initiate unblocks on dependent objects/views.


Display Related System Attributes

These attribute relate to what is going on concerning the currently visible panels, and status bar displays etc.

Name Read / Write Description

Current Screen Visible R/W This can be either Read or Set. To Read: Ask the model if the screen is visible: returns 1 if visible, 2 if it is not. This way you can detect what the user is looking at, and perhaps alter the animation to suit them. To Set: Assigning a value of one to the screen visible attribute makes the screen visible! You might think of using this to jump to screens if errors or interesting behaviour occurs.

Owner of Panel Visible R This returns true (1) if the panel containing the current panel from where the attref is scoped is visible, otherwise it returns "2" for false. This is useful for event handlers which reside in a subsystem "under" a panel which an end user sees/interacts with. It enables routine code to determine if the subsystem immediately above is visible without requiring object or panel indices.

Visible Portal Index R If the main visible panel is a subsystem of a portal with an object label, that label index is returned. If the top level window is visible, 0 is returned. Otherwise the value is -1

Lock Drawing W Set to 1 to stop updates to the screen. Set to Zero to resume updates. May need to force a repaint after that to be sure.

Activity State (0..100) W Shows an activity bar in the status bar. Value of 0..100 controls length of bar, 0 to reset (no bar). Automatically reset at start and end of run. Up to modeller how it gets used. Since this updates even when running without animating, use carefully to avoid model slowdown

Activity State (0..1.0) W Shows an activity bar in the status bar. Value of 0..1 controls length of bar, 0 to reset (no bar). Automatically reset at start and end of run. Up to modeller how it gets used. Since this updates even when running without animating, use carefully to avoid model slowdown.

Activity Bar Colour W Use a Value from the _Colours Label list to set the colour of the Activity bar.

Mouse X, Mouse Y R Returns the current Mouse Position Coordinates.

Visible Panel ID R Returns the panel index of the currently visible/front most panel. (This is the _Model Panels Label List, not _Model Objects).

Lock Portals from Drags W Enables the modeller to lock portals from being dragged at runtime even though their options setting enables this. This gives the modeller more control over when users can reposition portals in their display.

Trace Animation W Set to 1 to turn on the Trace Animation debugging option. Set to Zero to turn it off again.

Timer Broadcast Interval (ms) W Lets the modeller change the timing interval of the "_Real Time Tick" broadcast. A range of 10ms (100 times a second) to 1000ms (once a second) is now supported. 100 times a second will be too fast for slower systems so be careful on using the faster rates.

Enable Table Cell Edit R/W This enables the modeller to decide whether a cell edit should occur when a table cell is clicked, using the cell click broadcast. If the model sets this attribute nonzero while processing a table cell click broadcast (before edit) then the edit will actually occur. If this attribute is not set, the edit will not occur (as is current). This attribute is reset to 0 before each cell click broadcast gets sent. It is only valid to set/read this attribute in the initial thread of a cell click broadcast. For this feature to work, the table view option "Don’t Defer BC on FEC" must be enabled. This forces PL to send the BC immediately rather than waiting until a "safer" time. With this option "on" the modeller MUST NOT close the panel containing the table view as a result of the cell click broadcast, otherwise the platform will crash.

Animation Update Interval R/W Enables a model to control how often animation updates occur (0 sets none, model advances to model events only). See note below. The way the Animation Update Interval is handled. Planimate® always delays a minimum of 15ms every animation update interval regardless of whether there is item animation or not. This makes model time flow more smoothly especially if time based portal animation is being used. If a model spends a long time without animation which you want to skip, you can now set the animation update interval system attribute to make the model advance without showing the "Advance" dialog.

Time Scaling R/W Sets the Real Time Scaling value that is found under Run in the Menu Bar.

Item Animation Speed R/W Sets the Item Animation Speed value that is found under Run in the Menu Bar.


Table Related System Attributes

Relating to the currently-referenced table in a routine operation.

Name Read / Write Description

Table Rows R This gives access to the rows/column count for the table being referenced by the overall attribute reference. The advantage is that they can be used directly in a row or column index without having to use a separate temporary attribute and a separate routine line to set it. These attributes can determine a table from: direct references within an attref; dynamic table references; item table references (if item is available); implied (eg: a sort column attref in a sort knows the target table even though that table hasn't been directly specified in that attref

Table Columns R As above.


Other (General) System Attributes

Name Read / Write Description

Null W Enables dialog results etc. to be thrown away without having to create a dummy attribute.

Runtime Break Point Control W Provides convenient control of any breakpoint(s) in the model. This works in addition to modeller defined breakpoint control attributes, enabling breakpoints at complex conditions or at certain stages in a long loop to be activated.

Current Object Location R Lets you get an owning portal location for an object without involving an item. In other words, it obtains the location from the object's point of view rather than going via the item. This can be useful when you need to find the subsystem that a specific object is in, perhaps so you can direct a message to this location.

Total Object Label Count R With this attribute, the model can query the number of objects which are in the _Model Objects label list

ODBC Error Status R ODBC operations have an option to not stop the run on error. This system attribute returns whether an error in the ODBC operation occurred, non zero value indicates an error. ODBC Error Status must be read in the same thread that performs the ODBC operation.

Spatial link Scan Depth W Limits how deep PL will scan a spatial net looking for the closest route to the target. The attribute needs to be set each time the model is loaded, it is not saved. The default is 9999999 (ie: don’t limit search depth). Setting this value means Planimate® may not chose the shortest distance path in a spatial net if it contains more intermediate nodes than an alternative which is further in distance, and the node limit happens to be exceeded in scanning the shorter path. This will be obvious in incorrect animation but should not affect the item arrival time. In other words, reducing the search depth may cause PL to chose a route which is not the "shortest". It may also cause Planimate® not to find the correct route at all (if it has too many intermediate nodes) in which case PL will report a flow error. This attribute has to be set before firing the first item into the spatial net. It doesn't get saved with the model, it resets to a large number when the model is loaded. You can change its setting during the run but probably not something useful to do, if its too low and PL fails to find a target it will stop the model with a "no outgoing flow" type message.

User Edited Model Data R Gets set when a user edits an attribute view or table view/editor. The model can set and reset this attribute. It gets reset when the model is saved. Tables and attribute views have an option to not set this bit when they are edited

Button Paint ID R Set while a paint object checks its visibility/state attribute reference. If the object is in the paint label list, it can be used to assist in looking up visibility for that paint object.