You are here: Introduction > Modeling/Getting Started > Logic > System

System

---

ProModel offers statements that allow you to debug, animate, and otherwise manipulate and track your simulations.

Animate

The Animate statement allows you to control the animation speed of your simulation. Use the Animate statement when you want to slowly observe or quickly skip over a portion of your simulation.

To use the Animate statement, use the syntax

Animate <number> 

where number is a number between 1 and 100 that represents your desired animation speed. The higher the value in the number field, the faster the animation.

Example

Let’s say the overall animation speed of your simulation is set to the default 25, but there is a particular portion of your model that you would like to move slower so that you can observe the results more closely. You would define the statement

Animate 10 

at the desired Location to slow down the animation speed to 10 every time an Entity enters that Location.

Debug

The Debug statement allows you to open the model debugger during your simulation, which will then allow you to step through your created Logic one statement at a time to verify your code and examine Variable and Attribute values. Use the Debug statement if something in your model Logic is not working the way you would like it to.

To use the Debug statement, include it in the Logic of your model wherever you would like the model debugger to open.

Debug

Once an Entity reaches a Location or Route where the Debug statement is defined, the model debugger will open.

Use the Run button to continue the simulation until the next instance of the Debug statement.

Use the Next Statement button to step to the next Logic statement in your model.

Use the Options button to view further options for debugging your Logic.

Use the End Simulation button to end the simulation.

Trace

The Trace statement allows you to turn the tracing function on and off, which is used to follow the logical flow of a model. Trace listings will appear on a separate window on the screen.

To use the Trace statement, use the syntax

Trace “<message>” <Type> 

where message is the message you want to display in the trace listings when the Trace statement is encountered. The Type field allows you to choose one of the following options for your Trace statement:

Trace Step

The Step option makes ProModel wait for the user to click the left mouse button to execute the next statement or trace continuously while the right mouse button is held down. If the Type field is left blank, the Trace statement will default to the Step type.

Trace Cont 

The Cont option steps continuously without user intervention. Clicking the right mouse button will step through the Logic.

Trace Off 

The Off option turns tracing off but does not close the trace listing.

Trace Close

The Close option turns tracing off and closes the trace listing.

ResetStats

The Reset Stats statement allows you to reset the simulation statistics for your model. When a Reset Stats statement is encountered, all the statistics in the simulation are reset, not just the statistics for a particular Location or Entity.

To use the Reset Stats statement, include it in the Route or Location where you would like the reset to occur. The Reset Stats statement is often used with an If … Then statement to reset the statistics when a certain condition is met.

Reset Stats

If <Boolean expression> Then Reset Stats 

For more information about how If ... Then statements function, see the If ... Then Statements section of this guide.

Example

Let’s say you have a model that doesn’t work at full efficiency when operations are first started because it needs some time to get up to speed. It takes about four hours after start-up for your model to start working at its full possible speed. You have created your model to reflect this for the sake of authenticity, but you are only really interested in the statistics for what occurs after the model has gotten up to speed. To achieve this result, you would define the statements

{
	If Clock(hr) < 4
	Then Reset Stats
}

in the Logic of a chosen Location in your model. While less than 4 hours had elapsed in your model, every time an Entity entered the Location where the Reset Stats statement was defined, the simulation statistics would be reset. Once more than 4 hours had elapsed in your model, the Reset Stats statement would no longer execute, since the Boolean expression of the If ... Then statement would no longer be true. These statements would ensure that the simulation statistics would only include information for what occurred after the first 4 hours of the simulation.

For more information on the statements used in this example, see the If … Then Statements and Clock sections of this guide.

Read

The Read statement allows you to read the next numeric value from a Read file and assigns that value to a name. Read files are defined in the External Files menu; for more information see the External Files section of the Model Elements guide of this documentation. When reading from a file, ProModel skips all non-numeric data, such as text, and reads the next numeric value. Thus comments and notes may be included in a Read file. Multiple replications of a model will continue reading from a file where the previous replication left off unless reset with the Reset statement.

Please note that ProModel reads a period (.) in a Read file as a zero. To avoid this, you should use the comment symbol (//) in front of notes and comments that contain a period.

To use the Read statement, use the syntax

Read <file ID> <element name> 

where file ID is the name of the file as defined in the External Files menu and element name is the Variable or Attribute to be assigned the value.

Write

The Write statement allows you to write information to a Write file. Write files must first be defined in the External Files menu; for more information see the External Files section of the Model Elements guide of this documentation. The next item written to the file will appear immediately after this item. The Write statement always appends to the file unless the file is Reset. This holds true for multiple replications as well as single, independent runs. Any file that is written to with the Write statement automatically becomes a text file and will have an end of file marker attached automatically to the end when it is closed.

To use the Write statement, use the syntax

Write <file ID>, <”string text” or number>,<max digits before decimal>,<digits after decimal> 

where file ID is the name of the file as defined in the External Files menu and “string text” or number is the string or numeric expression to be written to the file. In the output file, quotes will automatically be added to string expressions so that most spreadsheet programs can easily read the file.

max digits before decimal is an optional field that defines the maximum number of digits before the decimal. This value is used to line up any numeric values into columns on the decimal point. This value may be any numeric expression. digits after decimal is also an optional field that defines the number of spaces to save after the decimal point. Use this option to line up any labels appearing after numbers.

Close

The Close statement closes a file that has previously been written to with Write, Writeline, Xwrite, or read with Read. Use Close when finished with a file to free system resources. A file will automatically be re-opened to be read or written if it has been closed. All opened files are automatically closed at the end of a simulation. When you are using many external files and you want to conserve system resources, this statement is especially helpful.

To use the Close statement, use the syntax

Close <file ID>

where file ID is the file ID of the desired file as defined in the External Files editor.

Reset

The Reset statement starts a general read file over from the beginning. Reset is used primarily in the Initialization or Termination logic to reset a general read or write file at the beginning or end of multiple replications and single, independent runs. Reset can also be used to re-read cyclic data in the same simulation run.

To use the Reset statement, use the syntax

Reset (<file ID>)

where file ID is the file identifier as defined in the External Files Editor. Note that the parentheses are optional and are included only to insure compatibility with older models.

Char

The Char function returns the ASCII character for the number that the expression evaluates to. This function is most useful for outputting ASCII characters that cannot be typed, such as accented characters. This function is most often used in conjunction with a string expression and the concatenation (“$”) operator.

The number corresponding to the ASCII character varies with each computer depending on the character set specified in the config.sys file of your computer. To determine the number corresponding to the ASCII character at your computer, run the model CHAR.MOD found in the MODELS\REFS directory. View the file this model generates called CHAR.TXT found in the same directory as the model.

To use the Char function, use the syntax

Char(<expression>)

where expression is any expression that evaluates to a number between 0 and 255. The expression is evaluated every time the Char function is encountered.

DynPlot

The DynPlot statement is used to automatically turn on predefined Dynamic Plot windows. Its usage is similar to that of the View statement. Dynamic Plot windows are predefined during simulation mode. These predefined Chart views can then be called from any logic statement, invoking the display of the designated chart during simulation.

To use the DynPlot statement, use the syntax

DynPlot “<chart name>”

where chart name is the name of the Dynamic Plot chart as defined in the Dynamic Plots dialog. Enclose the name in quotation marks.

Format

The Format function converts a number to a string in the format specified. Format should most often be used with the concatenation operator (“$”) and another string. Format is often used in conjunction with the Xwrite statement to produce formatted output.

To use the Format function, use the syntax

Format(<expression>, <total number of characters in expression> {,<digits after decimal>})

where expression is the expression that you would like to be evaluated and converted into a string. If the expression results in an integer, it will be converted to a real. The field total number of characters in expression formats the number so that it occupies a total space equal to the number of digits before + number of digits after the decimal + one character for the decimal point. For example, if you were to do the following logic:

Xwrite file1 Format (10.0 4 1) Xwrite file1 Format (1.0 4 1)

it will show up in the file as 10.0 1.0 with a space before the 1.0.

The digits after decimal field is an expression that evaluates to the maximum number of digits to the right of the decimal. If there are more digits to the right of the decimal than this number, the excess digits will be truncated. If there are fewer digits, ProModel will pad the number with zeros.

Report

The Report statement calculates and reports the current statistics to the output database. This is useful to get a snapshot of the model while it is running.

To use the Report statement, use the syntax

Report {With Reset} {As <string expression>}

The Report statement may be followed by the With Reset option to reset the statistics after the report is made to the database. When you use the With Reset option, you generally want to provide some looping or event creation that will call the report function at the appropriate time.

Used with the As option, Report creates a report with the name specified in the expression that can be accessed in the Output Program when creating a General Stats report. The string expression field in the As option is a unique name given to the report so it can be easily identified in the General Stats dialog in the Output Program. If any reports have the same name, a number is tacked on the end of the name to make it unique.

ThreadNum

Every time any logic is executed, it is executed by a thread which is assigned a unique number. The ThreadNum function returns the number of the thread that called the function. This function is most useful in conjunction with the If...Then and Debug statements to bring up the debugger at a certain process. Note that if the model does not change between simulation runs, every thread will have the same number from run to run, but not from replication to replication. Also, most changes in a model will cause threads to have different numbers on subsequent runs.

To use the ThreadNum function, use the syntax

ThreadNum()

to return the number of the thread that called the function.

View

Use the View statement to change the view in the Layout window from within your logic. Once the view has been defined from the View menu in main menu, you can use it in the logic.

To use the View statement, use the syntax

View “view name”

where view name is the name of the view defined in the Views dialog. Enclose the name in quotation marks.

WriteLine

The WriteLine statement writes information to a general write file and starts a new line. Writeline always appends to the file unless the file is Reset. Any file that is written to with WriteLine automatically becomes a text file and will have an end of file marker attached to the end when it is closed. Write and Writeline automatically separate values by commas.

To use the WriteLine statement, use the syntax

Writeline <file ID>, <string or numeric expression>{,<maximum digits before decimal>, <digits after decimal>}

where file ID is the name of the file as previously defined in the External Files Editor.

The string or numeric expression field is the string or numeric expression to be written to the file. In the output file, quotes will automatically be added to string expressions so that most spreadsheet programs can easily read the file.

When writing real numbers, the maximum digits before decimal field determines the maximum number of digits before the decimal. Use this value to line numbers on different lines up on the decimal.

When writing real numbers, the digits after decimal field determines the maximum number of digits after the decimal.

Xwrite

The Xwrite statement writes information to a general write file in any text format the user chooses. Xwrite is for writing user-formatted files, while Write and WriteLine are for writing special formatted text files. Xwrite always appends to a file unless the file is Reset. Note that any time a Write or WriteLine writes to a file, the file will automatically be a text file. No end of file marker is appended to files written only with Xwrite. In subsequent replications, additional items are appended to the end of the file unless the file is Reset. ProModel does not format the string expression, although you can use the Format statement to manually format data. To add an end of file marker to a user-formatted file, use Xwrite Char(26).

To use the Xwrite statement, use the syntax

Xwrite <file ID>, <string or numeric expression>

where file ID is the name of the file as previously defined in the External Files Editor and string or numeric expression is the string expression to be written to the file.

Xsub

The Xsub function calls an external subroutine inside a DLL file. Xsub is perhaps the most powerful statement in ProModel, because by using it the user can access the entire functionality of any 32-bit Windows programming language such as C, C++, Delphi, or Visual Basic. Xsub can be used for sophisticated file IO and to make simulations interactive. In fact, subroutines called with Xsub can do anything that the language they were written in allows. Because of its power, however, Xsub should be used with caution. When called, the simulation is suspended until the external subroutine finishes execution.

The subroutine inside the DLL must have been compiled as exportable by a Windows 32-bit compiler and have a return type of IEEE format double real. Xsub will copy the parameters following the function name to a block of memory, then pass the function a pointer to that block of memory.

The function can take only one parameter: a pointer to void. But the function may access any number of parameters through structure overlaying. The function should define a structure to match the type and order of the parameters, and assign the pointer just passed to a pointer to that type of structure. The parameters can then be used through structure overlaying. Integers are passed as four byte values and reals are passed as eight byte IEEE values.

Please Note: For Windows Programmers Only The handle to the run-time simulation frame window will be the last parameter passed. Most subroutines can completely ignore this parameter, but it will be needed if the subroutine displays a window.

To use the Xsub function, use the syntax

Xsub(<file ID>, <ordinal function number> or <function name> {, <parameter1>, <parameter2>...})

where file ID is the file ID assigned to an external DLL file as defined in the External Files editor. This file should be a 32-bit Windows DLL file.

The ordinal function number paramenter represents the ordinal number of the function inside the DLL. This function must be exportable. When DLL’s are compiled, every exported function inside them is numbered. The individual functions can then be accessed by calling the program by number. This field may be an expression that evaluates to an ordinal function number that is valid inside the DLL. Use an ordinal function number or the function name.

The function name parameter represents the name of the function inside the DLL. This function must be exportable. Note that when most compilers compile DLL’s, they adjust the name of the functions inside them. The function name inside the Xsub statement must be the adjusted name, not the original name. Most C compilers add an underscore to the function name; so a function called “Test1” would be compiled as “_Test1.” For most C++ compilers, valid ProModel external function names will be mangled to “@<function name>$pv.” Different compilers will vary, however, so the user should be aware of the particular compiler’s quirks.

The parameter fields should be the parameters to pass to the function. These may be any Variable, number, or expression. They are only limited by the type of field or logic that uses the Xsub function. Each parameter should be separated by a comma. See above for how the external subroutine will access these parameters.