Chapter 8 - PLUS: The Programming Language Under Simulation
A GPSS World Model is a sequence of Model Statements. A Model Statement may be either a GPSS Statement or a PLUS Procedure definition.
PLUS Expressions can exist as operands in GPSS Statements as well as within PLUS Procedures. Expressions can contain Procedure Calls which invoke either built-in or user defined PLUS Procedures. In addition, all the Stream Input/Output operations are available as built-in library procedures. This means that you can read from and write to files using GPSS Blocks or by calling the corresponding library procedures, or by using a mixture of both. Not only that, but now you can invoke external programs that exist on your system in EXE or DLL files by using the new Dynamic Call Procedures.
This chapter contains reference information on the PLUS language, and on the built-in procedure libraries you can access through it.
How this Chapter Describes Syntax
The valid form of individual PLUS Statements and Procedure invocations is indicated in a syntax line at the beginning of the statement description. Completing a PLUS Statement is similar to filling in the blanks of a form. The syntax line describes the constant and variable parts of the statement. It is up to you to "instantiate" the variable part of the statement in order to make it do what you want it to.
The items in the syntax line tell you how to code the statement. The following rules are observed:
1. Keywords are shown in the syntax line as all caps bold. These words, and unitalicized parentheses, must be entered as given. However, when you code the statement, capitalization of keywords is optional. For example,
ReturnString
= LEFT( SourceString, MaxCount )contains the Procedure Name "Left" in all caps. Although you can change the case of the letters any way you like, you must still include the word "Left" and the parentheses when you invoke the Procedure. When used as a PLUS Assignment Statement, a semicolon terminator must be added.
2. The data type of the result of a Procedure invocation is given in the syntax line to the left of an equal (=) sign. Procedures can be invoked from a PLUS Procedure Call Statement, in which case the unassigned result is discarded. In a PLUS Assignment Statement, an "lvalue" (named value or matrix element) is required to the left of the equal sign. It receives the result of the Procedure invocation.
3. Arguments are given in the syntax line as capitalized bold italic semantic variables. They indicate that you must make a selection from a class of possibilities. The definition of each argument follows the grammar line. That’s where the arguments are defined, and the possible choices for instantiation by you are given in one or more non-bold italic syntactic variables, such as in ‘Must be ParenthesizedExpression". That means that you are to use a valid PLUS Expression enclosed in parentheses when you code the statement. Syntactic variables are defined formally in the Appendix.
The valid forms you are to use in the instantiation of syntactic variables is described in the next few sections. The statement and Procedure descriptions follow that.
Procedures are commonly used in two different ways. They can be used for their effects on global variables and named values or to return a value to an expression.
If you simply wish to update a global variable or change a named value, no Return Statement is needed. In all cases where the result of a PLUS Procedure will be used where the Procedure was called (e.g.. in an operand or another PLUS expression), a Return Statement is necessary.
It’s easy to define a PLUS Procedure. All you have to do is to place a valid PROCEDURE Statement in a Model File and Translate it with the model, or send a PROCEDURE Statement to an existing simulation. Thereafter, you can invoke your Procedure in an Expression evaluation or a PLUS Assignment Statement just like any other Library Procedure.
As a simple example, consider the following PROCEDURE Statement:
PROCEDURE SetPop(Pop_Level) Foxes = Pop_Level ;Although most Procedures are more complex, this is all that is needed to define one. It doesn’t even declare a return value, so a value of 0 would be used by default. The sole purpose of this Procedure is to use the value, Pop_Level, that is passed to the Procedure and set the named value, Foxes, equal to that value. This, or any other PROCEDURE Statement, could even be sent to an existing simulation to define or redefine a Procedure named "SetPop". Then, any PLUS Expression in the simulation could include a Procedure call such as
SetPop(Rabbits/10);
to assign a value to the user variable
Foxes. Of course, here we assume that the User Variable RABBITS has already been given a value.You can define temporary Matrix Entities and temporary User Variables that exist only throughout an invocation of a Procedure. This is done using the TEMPORARY Statement in the Procedure Definition.
When a PLUS Procedure is invoked by a Procedure Call, one statement in the invoked Procedure is "performed" or "executed" after another. Most Procedures are defined as an outer Compound Statement containing a Statement List. Normal execution of a Statement List is to perform each Statement in succession. Compound Statements, IF Statements, IF-ELSE Statements, WHILE Statements and GOTO Statements may alter the normal sequence of execution. If a RETURN Statement is executed, the Procedure invocation is terminated and any memory used by it is released.
You do not really need a RETURN Statement in a PLUS Procedure. If, during an invocation of your Procedure, processing ever reaches the end of the Procedure’s Statement List, the invocation of the Procedure is terminated and a value of 0 is returned. Something is always used as a return value, in case one is needed in an Expression evaluation. If you do not specify an Expression in your RETURN Statement, or if your last statement in the Statement List is completed, a zero result is used.
If you have PLUS Procedures you use in more than one model, you can keep them in a source file, called a User Procedure Library. You can then use the INCLUDE Command to bring in your Library into each model that needs it.
The remainder of this chapter discusses all the features of the PLUS language, and all the built-in Procedures available for your use within a simulation.
You can incorporate either PLUS Expressions or PLUS Procedures and Experiments, built using the PLUS Language, into your GPSS World models. To do so, you must be familiar with both the building blocks of the language, and how to put them together. These are the topics of the remainder of this chapter.
The GPSS World character set consists of naming characters and special characters. Naming characters include the uppercase letters
A-Z, the Lower case letters a-z, the digits 0-9, and the underscore character ( _ ).The special characters are used to denote operators and punctuation. They are:
# * & + - / \ , ;The ^ character is also considered as an operator.
Normally, the # character is used as the multiplication operator and the * character as the GPSS SNA indirect addressing operator. If you prefer, you can reverse these by selecting "Switch * and # " in page 1 of the Settings Notebook. Use Edit / Settings on the Main Menu to do this.
We recommend that you use a consistent style when you use upper or lower case letters. Your model will be much more readable if you do. For example, you could make your User Variables stand out as all caps, or you could make keywords stand out. On the other hand, capitalized words (first letter upper case, the rest lower) tend to be easiest to read.
Names are character sequences created by you to identify entities, variables, and program locations. The naming characters are letters, digits, and underscore.
There are a few rules you must follow when you create a name. You must use from 1 to 250 naming characters, and you must start the name with a letter. In addition, your name must not be the same as a GPSS World keyword, System Numeric Attribute, or SNA Class. The keywords are listed in the Appendix.
GPSS World is case insensitive. The upper/lower case distinction does not matter. Only the characters in string constants and comments retain lower case. All other lower case letters are converted to upper case internally. This removes the danger of spelling two variables the same but having them refer to distinct values.
Your primary job when creating a name is to avoid keywords. You can refer to the list of keywords in the Appendix, if you like, but there’s an easier way. All you have to do is to include an underscore somewhere in each name, after the first character, which must be a letter. That will guarantee that you will not clash with GPSS World keywords.
Named Values
Named Values are names that you have placed in a Label field or PLUS Assignment Statement. You can use them to identify an entity or to hold a value. If you use them to label a GPSS Statement defining an entity, they are called Entity Labels. If you create them by assigning a value, as in an EQU Command or PLUS Assignment Statement, they are called User Variables.
Named Values normally have global scope. You can refer to them anywhere in the model. There are two kinds of Named Values, Entity Labels and User Variables.
GPSS Entity Labels
Entity Labels are names you use in an entity creation command. Unlike User Variables, Entity Labels are automatically given a system assigned number, normally a unique integer greater than 9,999. When you refer to a labeled entity, GPSS World first retrieves the Entity Number stored as the value of the Entity Label. The Entity Number is a strictly positive integer, that is used by the Simulation Object to find or create any GPSS entity.
Except for Block Labels, you can assign your own value to an Entity Label. Generally, you should do that only BEFORE you use the name to define any entity. Why? Because the Entity Number is set at the time of creation of the entity. If you then change the value of the label to something else, you will not be able to address that entity. In other words, if you want to use an EQU Command to assign your own entity number, put it early in the model, before the entity definition statement.
User Variables
A User Variable is a Named Value not used as an Entity Label. You can give it a numeric or string value, and you can integrate it as a continuous variable.
User Variables can be global, usable throughout the model, or local, usable only within a single PLUS Procedure. The latter are declared in a Temporary Declaration in the PLUS Procedure in which it is defined. All other User Variables are global.
You can assign a value to a User Variable through EQU Commands, through PLUS Assignment Statements, or through numerical integration, setup by an INTEGRATE Command.
User Variables must be initialized before they can be used. You must assign values to them before you can use them in Expressions or integrations.
You can observe the values of User Variables in online Plot Windows and Expressions Windows, which have been opened onto your simulation.
PLUS Statement Labels
You can use names to identify specific statements in a PLUS Procedure. To do so, simply begin the statement with a name followed by a colon. Such statements can then be targets of GOTO Statements. Both Labeled Statements and GOTO Statements are discussed below, in the section on PLUS Statements.
Statement labels have local scope. They do not clash with names defined outside the Procedure definition. This means that they neither refer to global objects, nor can they be referenced from outside the Procedure.
Procedure Names
You must name a PLUS Procedure or Experiment when you define it. Thereafter, you can invoke the same Procedure by a Procedure Call using the same name.
Procedure names are global in scope. Any Procedure can be invoked from any statement in the model. If you define a Procedure with a given name, any existing user defined PLUS Procedure with that name is redefined.
Experiments are special kinds of Procedures. They are identical to Procedures in syntax except that the keyword EXPERIMENT replaces PROCEDURE. Experiments can only be invoked by a CONDUCT Command.
Matrix Labels
Similar to User Variables, Matrix Entities can have local or global scope. A Matrix defined in a Temporary Matrix PLUS Declaration is local, known only with the Procedure in which it is declared. Such a Matrix is created when a Procedure invocation begins, and destroyed when it ends.
Global Matrix Entities are declared in a GPSS MATRIX Command. The Label you use becomes the Matrix Entity Label. Global Matrix Entities are permanent and may be referenced anywhere in the model.
All Matrices are created with uninitialized elements. You must assign values to them before you can use them in Expressions.
You can use a Matrix Window to view the dynamics of any cross section of a Matrix. In addition, you can observe the values of Matrix elements in online Plot Windows and Expressions Windows, which have been opened onto your simulation.
A PLUS Expression is a combination of one or more elements, called factors. Expressions are built by using operators and Procedure calls to combine factors. The rules for building Expressions are described in the next few sections.
Expressions can be used in PLUS Procedures and in the operands of GPSS Statements. Usually, when an Expression is used in a Block operand, it must be enclosed in parentheses. The list of acceptable syntactic variables will then include ParenthesizedExpression as one or the operand’s alternative forms. For compatibility some Commands do not need to use the outer parentheses, but if you always parenthesize Expressions used in GPSS Statements, you will be safe.
Data Types
Any User Variable, Matrix element, Savevalue, or Transaction Parameter can have a value on any of several forms called Data Types. Further, each has an uninitialized form which prevents its use before it has been assigned its first value.
The three major Data Types are Integer, Real, and String. The first two may be referred to as numeric Data Types.
Integers are 32 bit twos complement numbers. If, during arithmetic operations, an integer overflows, it is converted to a real number.
Real data items are double precision floating point numbers. They have a precision of 15 decimal digits and a range of exponents of -306 to 306.
Strings are sequences of ASCII characters. They can be any size, up to the maximum memory request declared in the "Simulate" page of the Settings Notebook. A whole class of String Procedures resides in the Procedure Library for creating and manipulating strings.
Data types are converted from one to the other explicitly by Procedure calls, or implicitly during the evaluation of Expressions. This is discussed further below.
Factors
Factors are the basic building blocks of Expressions. You combine them in Expressions which, in turn, can be used in GPSS Statement operands and PLUS Procedures. The detailed grammar is in the Appendix, but the following definitions should be suggestive.
The GPSS World Expression factors are:
"A stitch in time ...".1. String Constants, such as
2. Real constants, such as
201.6.3. Integer Constants, such as
17.4. Names, such as
Water_Level.5. PLUS Matrix elements, such as
6. Procedure Calls, such as
Word(X$Quote,2) or Myproc(X$Arg1,X$Arg2). Procedure calls must be Name(ExpressionList ).7. System Numeric Attributes, such as
AC1, F$My_Facility, MX$Mat1(2,1), and SR*My_Parm.You use operators and Procedure calls to combine factors into Expressions, using the rules associated with each operator or Procedure. These are discussed below.
Factors are defined formally in the Appendix.
Operators
The arithmetic operators of GPSS World Expressions are listed here in decreasing order of precedence. Note that the multiplication operator is normally
#, not * (which is the indirect addressing operator within System Numeric Attributes). You can switch the roles of # and * so that * denotes multiplication and # denotes GPSS indirect addressing. This is done by clicking a checkbox labeled "Switch * and #" in the first page of the Object's Settings Notebook (Edit / Settings).All arithmetic operators coerce string operands to numeric values.
The arity of an operator indicates the number of operands it requires. Unary operators always appear to the left of the operand.
Operators are either left or right associative. This is given in column 5, above. An operand surrounded by left associative operators of equal precedence is taken by the operator to its left.
Expressions are combinations of one or more factors, connected by operators, and evaluated according to a well-defined set of rules.
Evaluation
When an Expression is evaluated, values are determined and combined in order to calculate a final result. The following actions occur:
1. String and numeric constants evaluate to a copy of themselves.
2. Named Values evaluate to the associated value.
3. SNAs evaluate to a simulation or entity state value.
4. Procedure calls evaluate each argument, then return the result of the Procedure invocation. Built-in Procedures coerce the arguments.
5. Operators evaluate one or two operands, coerce the intermediate results to numeric values, and calculate the resulting value of the operation.
The Operators in GPSS World have a precedence order that affects how the Expressions you create are evaluated. For example, the exponentiation operator
^ has higher priority than the multiplication operator #. This means that the Expression4 # 3 ^ 2
is evaluated to a result of 36, not 144, because the first intermediate result is formed by evaluating the operator with the higher precedence. If you want a different order of evaluation than that implied by the operator precedence hierarchy, you should use parentheses to control the evaluation. Continuing the last example,
( 4 # 3 ) ^ 2
evaluates to 144.
GPSS World operators are "overloaded" in the sense that their operands are coerced to the proper data type just before the operation is applied. Therefore, you do not need to worry about data types when creating PLUS Expressions.
Truncations are not done automatically during Expression evaluation. To do so, you must either invoke Procedures that truncate, or you must run in GPSS/PC Compatibility Mode. In Compatibility Mode, the old GPSS rules are used to truncate SNAs and the intermediate results of VARIABLE and BVARIABLE evaluations. Compatibility Mode is discussed in Chapter 1.
Evaluation of Expressions
Expressions are combinations of mathematical operators, library functions, SNAs, and constants that obey the rules of elementary algebra. An Expression is evaluated according to the hierarchy of operators listed above, and otherwise left to right. The order of evaluation may be controlled by inserting paired parentheses.
Expressions may be evaluated, evaluated numerically, or evaluated as a string. The last two modes reflect an additional step applied after the normal evaluation.
When an Expression is evaluated numerically, a string result is converted to its numerical equivalent based on the numeric characters that begin the string. A string beginning with non-numeric characters is converted to numeric zero.
Similarly, when an Expression is evaluated as a string, any numeric result is converted to a string equivalent. In reports and Data Streams, the representation of large numbers can be controlled by suppressing scientific notation, as is done in the Model Settings Notebook: This is set in the "Reports" page of the Model Settings Notebook.
CHOOSE
Edit / Settingsthen select the Report page. Then set the checkbox marked "Scientific Notation" as desired. Scientific notation uses a base value followed by a power of ten. For example, eleven hundred would be represented as 1.1e
3 in scientific notation.Special rules apply when a simulation is run in GPSS/PC Compatibility Mode. This are discussed more fully in Chapter 1. In Compatibility Mode, SNAs are truncated, and when Bvariable Entities and Variable Entities are evaluated, intermediate results are truncated.
Data Conversion
In general, you do not need to worry about data types and conversions. All the work is done behind the scenes.
Data types are converted, as needed, when operated upon, or when processed as arguments to Procedures. For example, strings combined by an arithmetic + operator are converted to numeric values and the results are added together yielding a numeric result. Similarly, String Procedures that take a string as an argument, will convert a numeric value to its string equivalent, if necessary.
Data items are not changed by evaluation unless operated upon, or used as an argument to a Procedure. Arithmetic operators change arguments to numeric values before performing the operation, and all Procedures coerce each argument to the suitable form. This is done automatically.
Coercion only occurs to operand or an operator, or to arguments of a built-in Procedure during evaluation. The arguments of user defined PLUS Procedures are not coerced prior to invocation of the Procedure. However, the coercion of operand and arguments may occur within the body of the User Procedure, if required by the other PLUS Statements.
When an operand or argument is coerced to a string, any numeric value must be converted to its ASCII equivalent. Normally, extremely large or small numbers are presented in scientific notation in mantissa-exponent format. Scientific notation can be suppressed by a setting in the "Report" page of the Model Settings Notebook.
When a string is coerced to a numeric value, only the first characters that can be interpreted as numeric are used. If there are none, the string is converted to numeric 0. When a real value is coerced to integer, it is truncated toward 0. For example, 2.1 truncates to 2, and -2.1 truncates to -2.
Although GPSS Statements are restricted to a single line of text of up to 250 characters, PLUS Statements can span many text lines. PLUS PROCEDURE Statements may appear anywhere in the Model except in another PROCEDURE Statement. The other PLUS Statements can only appear inside a PLUS Procedure.
Only a small number of statement types are needed by PLUS to provide a powerful programming language. They are:
·
PROCEDURE - Define a PLUS Procedure.·
EXPERIMENT - Define a PLUS Experiment.·
TEMPORARY - Define and restrict the scope of a local User Variable or local Matrix.·
BEGIN / END- Compound Statement. Create a block of PLUS Statements.·
Assignment - Set the value of a Named Value or Matrix element.·
Procedure Call - Invoke a Library Procedure.·
Labeled Statement - The superclass of Statements that begin with a Label.·
IF / THEN - Test an Expression and act on a "TRUE" result.·
IF / THEN / ELSE - Test an Expression and act on the result.·
WHILE / DO- Perform action repetitively.·
GOTO - Jump to a new location within the Procedure.·
RETURN - Finish the processing and, optionally, give a result to thecaller.
For full examples of GPSS World Models using PLUS Routines, see the PLUS PRIMER in Chapter 17 of the GPSS World Tutorial Manual. Here we present the PLUS Statement Types in alphabetic order.
1. Assignment Statement
SyntaxValue = Expression;
LValue
- A Named Value or Matrix element.Expression - A well-formed PLUS Expression, defined above.
Intended Use
Assignment Statements are used to set the value of variables. You can assign any data type to a Named Value or a Matrix element. These may be restricted in scope by a TEMPORARY or TEMPORARY MATRIX Statement in the same PLUS Procedure.
Example
Alert = "TRUE";
In this example, the Named Value, Alert, is given the value of the string constant "TRUE".
Action
An Assignment Statement evaluates the Expression on the right side and sets the value of the Named Value or Matrix element equal to a copy of the result.
If the Name used for the LValue is declared in a Temporary Declaration in the current Procedure, the assignment goes to a temporary User Variable or Matrix with local scope. Otherwise, the Name is assumed to be a global reference to a permanent Matrix or User Variable known throughout the simulation.
2. Compound Statement
Synta
xBEGIN StatementList END;
StatementList
- A list of well-formed PLUS Statements. Instantiated by a sequence, possibly null, of PLUS Statements. Each PLUS Statement contains an internal semicolon terminator. Must be StatementSequence.
Intended Use
Compound Statements are used primarily in Procedure definitions, and to control the flow of action within a Procedure.
In a Procedure definition, a PLUS Procedure Statement requires a single statement in order to define a Procedure. A Compound Statement is generally used here, so that an arbitrarily complex PLUS Procedure may be defined.
Compound Statements are also used to group several PLUS Statements into a single block of statements. This is useful in IF Statements and WHILE Statements so that only a specific group of statements gets performed when a certain decision is made.
Example
PROCEDURE Decision(Indicator) BEGIN
TEMPORARY Return_Value;
Return_Value = Old_Indicator;
IF (Indicator > 0) then BEGIN
ALERT = "TRUE";
Old_Indicator=Indicator;
END;
ELSE Alert = "FALSE";RETURN Return_Value;
END;
In this example, Compound Statements are used in both ways. The PROCEDURE Statement includes a Compound Statement for holding the body of the PLUS Procedure. Internally, the "True" branch of the IF Statement uses a Compound Statement to cause more than one statement to be performed when the Expression in the IF Statement tests TRUE.
Action
A Compound Statement groups other PLUS Statements so they can be treated as a unit. A Compound Statement can be used anywhere a PLUS Statement is required.
3. EXPERIMENT Statement
SyntaxEXPERIMENT Name ( ArgumentList ) Statement
- A user-defined Procedure Name. Must be Name.Name
ArgumentList - A sequence of user-defined names, separated by commas, used a s formal argument list. Instantiated by a list of Name items, possibly null, separated by commas.
Statement - Procedure body. A PLUS statement. Must be Statement.
Intended Use
An Experiment is a special kind of PLUS Procedure. EXPERIMENT Statements are used to define special User Procedures used to control multiple runs of a Simulation. Normally, the statement used as the Experiment body is a Compound Statement.
Experiments are generally used in connection with the DoCommand() library procedure, to control the Simulations, and the ANOVA library procedure to automatically analyze results. Normally, the Experiment fills a Global Matrix Entity with results and passes it to the ANOVA procedure. You can create screening or optimizing experiments automatically using GPSS World's Automatic Experiment Generators, by opening the appropriate dialog in the Edit Menu of the Main Window.
An Experiment can only be invoked by a CONDUCT Command. The Experiment Generators will load a Function Key with the appropriate CONDUCT Command, if you like.
Experiments, and any simple Procedure called directly or indirectly by an Experiment, may use the DoCommand library procedure to execute GPSS Statements including Commands and Block Statements.
Example
An example of an Experiment is discussed in detail in Lesson 19 of the GPSS World Tutorial Manual.
Action
An EXPERIMENT Statement creates a User Defined Procedure. When it is Translated, the Procedure is added to the simulation’s Procedure Library, and is available for invocation by a CONDUCT Command.
The optional Formal Argument list passed to the Experiment by the CONDUCT Command is used to create temporary User Variables, addressed by the given names. Each receives a copy of the value resulting from evaluating the actual argument asserted in the Experiment invocation. Later references to the formal argument name refer to the variable created in this manner. The arguments are often used to specify which part of a response surface is to be explored by this invocation of the Experiment. With proper planning, Experiments can be HALTed, Saved, and restarted later.
While running, an Experiment takes control of the Simulation Object. Having begun an Experiment with a CONDUCT Command, your ability to interact with the simulation is limited. You can always display the running Simulation System Clock ( View / Clock ), but generally you will have to abort the Experiment in order to modify the Simulation. Then, unless you have planned ahead, you may have to restart the Experiment from the beginning.
4. GOTO Statement
SyntaxGOTO Label ;
Label
- A PLUS Statement Label. A unique name appearing on a Labeled Statement, defined below.
Intended Use
GOTO Statements are used to cause the processing sequence of a Procedure to jump abruptly to a specific statement, tagged with a PLUS Statement Label.
Example
GOTO Sanctuary;
In this example, when the PLUS Procedure comes upon the GOTO Statement, it immediately finds the statement with the label, SANCTUARY, and begins there.
5. IF Statement
SyntaxIF ( Expression ) THEN Statement
Expression
- A well-formed PLUS Expression, defined above. Must be Expression.Statement - Conditional statement. A PLUS Statement.
Intended Use
IF Statements are used primarily to conditionally perform a block of statements
Example
IF (Indicator > 0) THEN BEGIN
Alert = "TRUE";
Old_Indicator=Indicator;
END;
In this example, the Expression is evaluated numerically. True logical relations yield an integer 1 result. If the result of the evaluation is nonzero, the block of Assignment Statements is performed.
Action
An IF Statement evaluates an Expression numerically, and determines of the result is nonzero. If so, the Conditional Statement, which may be compound, is performed.
6. IF-ELSE Statement
SyntaxIF ( Expression ) THEN Statement1 ELSE Statement2
- Test Expression. A well-formed PLUS Expression, defined above. Must be Expression.Expression
Statement1 - True branch statement. A PLUS Statement. Must be Statement.
Statement2 - False branch statement. A PLUS Statement. Must be Statement.
Intended Use
IF-ELSE Statements are used primarily to choose between two statement blocks, only one of which is to be performed.
Example
IF (Indicator > 0) THEN BEGIN
Alert = "TRUE";
Old_Indicator=Indicator;
END;
ELSE Alert = "FALSE";
In this example, the Expression is evaluated numerically. True logical relations yield an integer 1 result. If the result of the evaluation is nonzero, the true branch statement is performed. In this case, the block of Assignment Statements is performed. If the result of numerically evaluating the test Expression is zero, the very last Assignment Statement is performed, instead.
Action
An IF-ELSE Statement evaluates an Expression numerically, and determines of the result is nonzero. If so, the true branch statement, which may be compound, is performed. Otherwise, the false branch statement, which may also be compound, is performed.
ELSE clauses pair with the most recent IF clause. If several IF Statements appear in succession just before an ELSE clause, the latest unpaired IF clause is paired with the ELSE clause to form an IF-ELSE Statement. You can avoid ambiguity by using Compound Statements within IF and IF-ELSE Statements.
7. Labeled Statement
SyntaxLabel : Statement
- A PLUS Statement Label. A unique user-defined name. Must be Name.Label
Statement - A PLUS Statement. Must be Statement.
Intended Use
Labeled Statements are used as the targets of GOTO Statements.
Example
GOTO Sanctuary;
...
Sanctuary: RETURN 100;
In this example, when the PLUS Procedure comes upon the GOTO Statement, it immediately finds the statement with the label, SANCTUARY, and begins there. In this case, the Procedure terminates returning a numerical value of 100.
8. PROCEDURE Statement
SyntaxPROCEDURE Name ( ArgumentList ) Statement
- A user-defined Procedure Name. Must be Name.Name
ArgumentList - A sequence of user-defined names, separated by commas, used a s formal argument list. Instantiated by a list of Name items, possibly null, separated by commas.
Statement - Procedure body. A PLUS statement. Must be Statement.
Intended Use
PROCEDURE Statements are used to define User Procedures. Normally, the statement used as the Procedure body is a Compound Statement.
Example
PROCEDURE Decision(Indicator) BEGIN
TEMPORARY Return_Value;
Return_Value = Old_Indicator;
IF (Indicator > 0) THEN BEGIN
Alert = "TRUE";
Old_Indicator=Indicator;
END;
ELSE Alert = "FALSE";
RETURN Return_Value;
END;
In this example, a PROCEDURE Statement is used to define a User Procedure. When Translated, the Procedure is integrated into the Procedure Library of the simulation. Thereafter, it can be invoked by an appropriate Procedure Call, such as:
Result = Decision(200+My_Constant);
Action
A PROCEDURE Statement creates a User Defined Procedure. When it is Translated, the Procedure is added to the simulation’s Procedure Library, and is available for invocation.
The Formal Argument list is used to create temporary User Variables, addressed by the given names. Each receives a copy of the value resulting from evaluating the actual argument asserted in the Procedure invocation. Later references to the formal argument name refer to the variable created in this manner.
Procedures have global scope. They may be invoked from anywhere within the simulation.
9. Procedure Call Statement
SyntaxProcedureName ( ExpressionList ) ;
ProcedureName
- An name used to define a Procedure in the Procedure Library. May be a Math Procedure, a String Procedure, a Probability Distribution, or a User Defined PLUS Procedure. Must be Name.ExpressionList - The argument list of the Procedure One or more well-formed PLUS Expressions, separated by commas. Must be ExpressionList.
Intended Use
Procedure Call Statements are used to invoke Procedures in the Library.
Example
Real_Value=Beta(1,100,200,2,2);
In this example, a sample is drawn from the Beta probability distribution. Pre defined Procedures are available for math and string functions, and probability distributions. They are discussed later in this Chapte
Action
A Procedure Call Statement invokes a Procedure in the Library. Pre-defined and User Defined Procedures may be called.
Expressions may be used as arguments to Procedures. They are evaluated at the very beginning of the invocation. The arguments of built-in Procedures are coerced to a specific data type. This is discussed in the documentation of the specify Procedure. The arguments to User Defined Procedures are evaluated normally.
10. RETURN Statement
SyntaxRETURN Expression ;
Expression
- Optional. A well-formed PLUS Expression. Must be Expression or Null.
Intended Use
RETURN Statements are used to terminate the processing of a PLUS Procedure, and to establish the result value to be used as the result of the Procedure invocation.
Example
RETURN "Success";
In this example, a RETURN Statement is used to complete the Procedure and to establish a string constant as the result of the Procedure invocation.
Action
When a RETURN Statement is performed, the Expression in the RETURN Statement, if any, is evaluated normally. The Procedure is terminated, and all temporary Named Variables and temporary Matrices are deleted. If an Expression was asserted in the RETURN Statement, its result is used as the result of the Procedure. If there is no Expression, integer 0 is used.
11. TEMPORARY Statement
Syntax for TEMPORARY declarationTEMPORARY NameList ;
Intended UseNameList
- Name List. A list of user defined names to become local User Variables. Namelist is instantiated by a list of Name items separated by commas.Syntax for TEMPORARY MATRIX declaration
TEMPORARY MATRIX Name[ IntegerList ] ;
Name - A user defined local Matrix name. Must be Name.
IntegerList - A sequence of 1 to 6 strictly positive integers, separated by commas. The number of elements in each dimension of the Matrix. IntegerList is instantiated by a list of up to 6 PosInteger items, separated by commas.
TEMPORARY Statements are used to create Named Values and Matrices that exist only during the invocation of a PLUS Procedure.
Example
TEMPORARY Return_Value,Accumulator;
TEMPORARY MATRIX DataArray[2,3,4];
In this example, two TEMPORARY Statements are used in a Procedure. The first creates two Named Values for use within a single Procedure invocation. The second creates a 3 dimensional local Matrix named DataArray.
Temporary data are not automatically initialized. You must assign data to temporary Named Values and Matrix Elements before you can refer to them in Expressions.
Action
A TEMPORARY declaration creates one or more uninitialized Named Values for used during a single Procedure invocation.
A TEMPORARY MATRIX declaration creates a single uninitialized Matrix, of up to 6 dimensions, for use during a single Procedure invocation.
TEMPORARY Named Values and TEMPORARY MATRICIES have local scope. They can be accessed only within their containing Procedure, and not by Procedures invoked from the containing Procedure. Named Variables and Matrices not declared in temporary declarations have global scope, are known throughout the Model, and exist for the life of the simulation. A global matrix must be defined in a GPSS MATRIX Statement.
When a Procedure terminates, all of its temporary Named Values and temporary Matrices are freed.
12. WHILE Statement
SyntaxWHILE ( Expression ) DO Statement
- Test Expression. Required. A well-formed PLUS Expression, defined above. Must be Expression.Expression
Statement - Target statement. Required. A PLUS Statement.
Intended Use
WHILE Statements are used primarily to perform repetitive actions.
Example
Accumulator=1;In this example, a Compound Statement is performed repetitively in a while loop. If X_Integer is a positive integer, the while loop will continue to accumulate the factorial of X_Integer in the Named Value, Accumulator.
Each time the target statement is performed, the Named Value Counter is incremented. When Counter becomes larger than X_Integer, the target statement is not performed, and processing continues with the statement after the WHILE Statement.
Action
When a WHILE Statement is encountered, the test Expression is evaluated numerically. If the result is nonzero, the target statement is performed, and the "Test-Perform" process is repeated. If the test Expression is zero, the target statement is not performed, and instead, processing continues with the statement following the While Statement.
To avoid a nonterminating loop, you must ensure that the evaluation of the test Expression becomes zero, at some time. Normally, this is done somewhere in the target statement by an Assignment Statement or Procedure call.
A Procedure must be in a Procedure Library for you to invoke it during a simulation. There are two kinds of libraries. The User Library and the GPSS World Library. The User Library is the collection of PLUS Procedures you have included in the Model. The GPSS World Library contains a set of ready made mathematical and string Procedures that you can invoke in any PLUS Expression.
The Procedure library is a set of PLUS Procedures that you can call in Expressions. Some Procedures are supplied for you, but you can define and add your own Procedures as well.
The built-in part of the Procedure Library includes Utility Procedures, File Procedures, Dynamic Call Procedures, Math Procedures, Probability Distributions, String Procedures, and Query Procedures
The GPSS World Procedure Library includes important Utility Procedures needed for the control of simulation runs and analysis of Experiments.
1. DoCommand - Translate and Execute a GPSS Statement
Syntax
DoCommand( CommandString
Arguments
CommandString
- A string representation of the GPSS Statement to be executed. Required. Coerced to string. The argument must be Expression.
Return Value
None.
Example
DoCommand("SHOW ""This is my string"" " );
Action
DoCommand translates its argument string in global scope and then sends the result to the simulation for execution. Only Experiments or Procedures invoked during an Experiment can invoke the DoCommand library procedure. It is this powerful procedure which allows the Experiment to control the simulation environment.
Since the string is Translated in global scope, Temporary Variables and Arguments are not accessible and should not be represented in the command string.
In its invocations, a string containing a Command or Statement is Translated in the global context and then executed by the Simulation Object.
Here are some tips for using the DoCommand library procedure.
1. The PolyCatenate String Procedure can combine any number of strings.
2. Use 4 double quotes around strings within strings. Each inner string should be sandwiched by pairs of double quotes, which get reduced to single quotes when translated.
3. Do not pass a string to DoCommand that contains the name of a TEMPORARY variable or argument because these variables are not accessible in global context. You can always use them in a string created before the call to DoCommand.
Normally, GPSS World simulations enqueue all commands (except HALT and SHOW) on a low priority Command Queue and work on them one at a time until the queue is empty. However, DoCommand behaves a little differently. It does not return to the calling procedure until the low priority Command Queue is empty. This means that after a START Command issued through the DoCommand library procedure returns to the calling Procedure, the simulation has completed and is ready for the results to be extracted.
2. ANOVA - Perform Multiway Analysis of Variance.
SyntaxStandardError = ANOVA( ResultMatrixName, ReplicateDimension, InteractionLimit )
Arguments
ResultMatrixName
- The GPSS Matrix containing the results to be analyzed. Required. May be a GPSS Matrix of up to 6 dimensions of any shape. The argument must be Name.ReplicateDimension - The dimension of the Result Matrix used for replicates. Use 0 if there are no replicates. Required. Coerced to integer. The argument must be Expression.
InteractionLimit - The Limit of Factor Interactions to be analyzed. This value can be 1, 2, or 3. It is normally used to preserve Degrees of Freedom for the estimate of the Standard Error instead of using them on an interaction presumed to be unimportant. Required. Coerced to integer. The argument must be Expression.
Return Value
StandardError
- The Standard Error of the Analysis of Variance is returned. If an error occurs, the value 0 is returned. Real.Example
SHOW ANOVA(ABC,1,1)
3.8756
This example uses a SHOW Command to demonstrate how the ANOVA Procedure can be invoked, returning the Standard Error of the Analysis of Variance. The ANOVA Procedure also produces an ANOVA Table and a table of descriptive statistics and writes them to the Journal Window.
Action
The ANOVA Procedure analyzes the data in the Result Matrix, excluding any element with the UNSPECIFIED Data Type. If a Replicate Dimension is specified in the ANOVA invocation, that dimension of the matrix is presumed to contain the results of replicate runs and is used exclusively to estimate the Standard Error. Two and Three level interactions between factors are normally included in the analysis, unless they are restricted by the third argument. If the third argument is 2, only 2-way interactions are estimated, if 1, no interactions are estimated. Restricting interactions presumed to be 0 has the benefit of providing a better estimate of the Standard Error.
If possible, the ANOVA Procedure writes an ANOVA Table and a table of descriptive statistics to the Journal Window. The resulting Standard Error is returned by the procedure.
If a GPSS Table Entity exists with the name ResultMatrixName_Residuals, where ResultMatrixName is the name used for the first argument of the ANOVA invocation, a table of residuals will be created in it based on the Analysis of Variance.
A full discussion of the ANOVA Procedure and its output is contained in Chapter 12. Also, Lesson 19 of The GPSS World Tutorial Manual treats the use of the ANOVA Procedure with User Experiments.
3. Exit - Conclude the GPSS World Session.
SyntaxExit( ExitCode )
Arguments
ExitCode
- -1, 0, 1 to specify "Save None", "Query Modified", or "Save All" open Model and Simulation Objects.Return Value
None
\Example
Exit( 0)
This example uses the Exit library procedure to conclude the GPSS World Session. If any Model or Simulation Objects have been modified, a dialog box will appear for each asking if the object should be saved to file or not.
Action
The Exit procedure HALTs all simulations, then closes all objects one at a time.
The Exit Code can be used to control the writing of Model Objects and Simulation Objects to files. If Operand a is 0, all modified files bring up a message box inquiring as to whether or not each object should be saved. If Operand A is 1, all Objects are saved. If Operand A is -1, no Objects are saved.
The Exit() Procedure is useful when sessions are run in Batch Mode which is discussed in Section 2.3.2.
The World Procedure Library includes several Mathematical Procedures. In all cases, the argument is coerced to a numeric value before the Procedure performs its operation. Angular data are in radians. Numeric values are returned as real numbers.
The Math Procedures are
ABS( Expression ) - Absolute value.
ATN( Expression ) - Arctangent in radians.
COS( Expression ) - Cosine. Expression must be in radians.
EXP( Expression ) - e raised to the power given by Expression.
INT( Expression ) - Truncation toward zero.
LOG( Expression ) - Natural logarithm.
SIN( Expression ) - Sine. Expression must be in radians.
SQR( Expression ) - Square Root.
TAN( Expression ) - Tangent. Expression must be in radians.
Transaction Query Procedures are available which return information based on any Transaction in the simulation. Except for QueryXNExist(), if you attempt to query a nonexistent Transaction, an Error Stop will occur. If there is any question, you should test for existence first.
All arguments are coerced to integers in order to look up either a Transaction or one of its parameters. The Transaction state query Procedures now include:
QueryXNExist( TransactionNumber ) - Return integer 1 if the Transaction exists in the simulation, integer 0 , if not.
QueryXNParameter( TransactionNumber, Parameter ) - Return the value of a Transaction Parameter. Error Stop occurs if the Parameter does not exist.
QueryXNAssemblySet( TransactionNumber ) - Return the integer Assembly Set of a Transaction.
QueryXNPriority( TransactionNumber ) - Return the integer Transaction Priority of a Transaction.
QueryXNM1( TransactionNumber ) - Return the numeric Mark Time of a Transaction.
The GPSS World Procedure Library contains a number of String Procedures that make it easy to manipulate string data types. As with all built-in Procedures, the String Procedures coerce arguments into proper form before processing them.
Strings are sequences of ASCII characters. The individual characters can be addressed by an index called an "Offset". String Procedures that must find a specific character use the Offset as a 1-relative index into an array of characters. The first character in the string is associated with an index of 1, the second with 2, and so on.
A null string is a string of length 0. It contains no characters, and is denoted " ". Null strings are still considered to be valid strings.
A word is a consecutive sequence of printable characters, not including blanks or tabs. Words may be separated by one or more blank and/or tab characters.
The remainder of this section describes the String Procedure Library. For each Procedure, the syntax of Procedure invocation is given in a syntax line. Any Procedure may be invoked in an Expression, without the assignment of the result, as well as in a PLUS Assignment Statement.
Align( InsertString, SourceString, Offset ) - Return a copy of one string placed in another, right justified.
Catenate( String1, String2 ) - Return a copy of two strings combined into one.
Copies( SourceString, Count ) - Create a string from many copies of a string.
Datatype( Datum ) - Return a string denoting the data type of the argument.
Find( TestString, SourceString ) - Return the Offset of one string in another.
Left( SourceString, MaxCount ) - Return a copy of a substring starting on the left.
Length( SourceString ) - Return the count of characters in a string.
Lowercase( SourceString ) - Return the lowercase representation of a string.
Place( InsertString, SourceString, Offset ) - Place one string in another. Left justify.
PolyCatenate( String1, String2, ... ) - Return a copy of two or more strings combined into one.
Right( SourceString, MaxCount ) - Return a copy of a substring starting on the right.
String( Datum ) - Convert a data item to its string equivalent.
StringCompare( String1, String2 ) - Return an integer result if string comparison.
Substring( SourceString, Offset, MaxCount ) - Return a copy of a substring of the string argument.
Trim( SourceString ) - Remove leading and trailing white space.
Uppercase( SourceString ) - Return the uppercase equivalent of a string.
Value( Datum ) - Return the numeric equivalent of a string.
Word( SourceString, WordNumber ) - Return a copy of one of the words in a string.
1. Align - Right justify a string.
Syntax
ReturnString=Align(InsertString,SourceString,Offset )
Arguments
InsertString
- The string to be copied. Required. Coerced to string. The argument must be Expression.SourceString - The string to be overwritten. Required. Coerced to string. The argument must be Expression.
Offset - The 1-relative offset in SourceString to receive the rightmost character of InsertString. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as a result of inserting InsertString into SourceString at offset Offset.Example
SHOW Align("ABC","123456789",6)
"123ABC789"
This example uses a SHOW Command to demonstrate how the align() string Procedure right justifies the insert string at position 6 of the target string, and displays the result.
Action
Align( ) coerces the first and second arguments to strings, and the third to an integer. It then creates a string of blanks large enough to contain the result, and copies the target string into the result string. Finally, it copies the insert string, or the part of it that fits, into the result string.
If the Offset is larger than the target string, the resulting string will be larger, as well. Any characters not specified by the argument strings will be blanks.
If the Offset is less than the length of the insert string, only the characters that fit will be inserted, starting from the rightmost character of the insert string.
If the Offset is not strictly positive, no characters will be inserted.
2. Catenate - Combine two strings.
SyntaxReturnString = Catenate( String1, String2 )
Arguments
String1
- The string to be first in the concatenated result string. Required. Coerced to string. The argument must be Expression.String2 - The string to be second in the concatenated result string. Required. Coerced to string. The argument must be Expression.
Return Value
ReturnString
- The string created as a result of placing String2 immediately after String1.Example
SHOW Catenate("ABC","123")
"ABC123"
This example uses a SHOW Command to demonstrate how the Catenate() string Procedure combines two strings.
Action
Catenate( ) first coerces both arguments to strings. It then creates a string large enough to contain the result, and copies the first string and the second string into the result string.
3. Copies - Build a string from multiple copies.
SyntaxReturnString = Copies( SourceString, Count )
Arguments
SourceString
- The string to be duplicated. Required. Coerced to string. The argument must be Expression.Count - The number of copies to make. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as a result of concatenating Count copies of SourceString.Example
SHOW Copies("ABC ",3)
"ABC ABC ABC "
This example uses a SHOW Command to demonstrate how the copies( ) string Procedure creates a string out of 3 copies of an existing string.
Action
Copies( ) coerces the first argument to a string and the second to an integer. It then creates a string large enough to contain the result, and copies the source string to the result string once for each count in the second argument.
If the count is not strictly positive, a null string results.
4. DataType - Determine the type of a data item.
SyntaxReturnString = DataType( Datum )
Arguments
Datum
- The data item to be examined. Required. The argument must be Expression.Return Value
ReturnString
- The string identifying the data type. One of:"INTEGER" - Datum is a 32 bit integer,
"REAL" - Datum is a double precision floating point number,
"STRING" - Datum is a character string, or
"UNSPECIFIED" - Datum has not been given a value.
Example
SHOW DataType("ABC")
"STRING"
This example uses a SHOW Command to demonstrate how the DataType() string Procedure identifies the data type of a string constant.
Action
DataType( ) does not coerce its argument. It determines the data type of the argument and returns the string constant associated with that type.
5. Find - Find one string in another.
SyntaxReturnInteger = Find( TestString, SourceString )
Arguments
TestString
- The string to be found. Required. Coerced to string. The argument must be Expression.SourceString - The string to be tested for occurrence of TestString. The argument must be Expression.
Return Value
ReturnInteger
- The 1-relative offset of the first occurrence of TestString in SourceString. A real value. Zero if not found.Example
SHOW Find("ABC","123ABC789")
4
This example uses a SHOW Command to demonstrate how the find() string Procedure finds the occurrence of "ABC" starting at position 4 of string "123ABC789".
Action
Find( ) coerces the first and second arguments to strings, and tests the second argument for the existing of a substring equal to the first argument. If it cannot be found, find( ) returns 0. Otherwise, find( ) returns the 1-relative offset in the second string of the first occurrence of the first string.
6. Left - Return an initial substring.
SyntaxReturnString = Left( SourceString, MaxCount )
Arguments
SourceString
- The source string to be used to create the substring. Required. Coerced to string. The argument must be Expression.MaxCount - The maximum number of characters to be used in the substring. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as the left MaxCount characters of SourceString.Example
SHOW Left("123456789",6)
"123456"
This example uses a SHOW Command to demonstrate how the left( ) string Procedure extracts the first 6 characters of the string "123456789".
Action
Left( ) coerces the first argument to a string, and the second to an integer. If MaxCount is less than 0, it is made equal to 0. Left( ) then creates a string of length equal to the smaller of MaxCount and the length of SourceString. The result string is then filled with characters from SourceString, starting with the first.
7. Length - Count string characters.
SyntaxReturnInteger = Length( SourceString )
Arguments
SourceString
- The string to be examined. Required. Coerced to string. The argument must be Expression.Return Value
ReturnInteger
- The number of characters in the string. A Real value.Example
SHOW Length("ABC")
3
This example uses a SHOW Command to demonstrate how the length() string Procedure returns the character count of the string "ABC".
Action
Length( ) coerces the argument to a string, counts its characters, and returns the count as an integer. Null strings have a count of 0.
8. Lowercase - Convert string to lower case.
SyntaxReturnString = LowerCase( SourceString )
Arguments
SourceString
- The string to be converted. Required. Coerced to string. The argument must be Expression.Return Value
ReturnString
- The string created as a result of converting SourceString to lower case.Example
SHOW Lowercase("123 AbC")
"123 abc"
This example uses a SHOW Command to demonstrate how the lowercase( ) string Procedure copies a string and converts the upper case letters to lower case.
Action
Lowercase( ) coerces the argument to a string, and creates a copy of the string. It then converts the upper case letters in the copy to lower case and returns it as the result string.
9. Place - Left justify a string.
Syntax ReturnString =Place(InsertString,SourceString,Offset )Arguments
InsertString
- The string to be inserted. Required. Coerced to string. The argument must be Expression.SourceString - The string to receive the insertion. Required. Coerced to string. The argument must be Expression.
Offset - The 1-relative offset in SourceString to receive the leftmost character of InsertString. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as a result of inserting InsertString into SourceString at offset Offset.Example
SHOW Place("ABC","/123456789",3)
"123ABC789"
This example uses a SHOW Command to demonstrate how the place() string Procedure left justifies the insert string at position 3 of the target string, and displays the result.
Action
Place( ) coerces the first and second arguments to strings, and the third to an integer. It then creates a string of blanks large enough to contain the result, and copies the target string into the result string. Finally, it copies the insert string into the result string.
If the end of the inserted string extends past the end of the original target string, the resulting string will be larger, as well. Any characters not specified by the argument strings will be blanks.
If the offset is less than 1, the leftmost characters of the insert string are truncated, and the remaining characters, if any, are inserted at position 1 of the target string.
10. PolyCatenate - Combine two or more strings.
SyntaxReturnString = PolyCatenate(String1, ... )
Arguments
String1,
... - The strings to be combined in order in the concatenated result string. Required. Coerced to string. The arguments must be Expression.Return Value
ReturnString
- The string created as a result of placing copies of the strings one after the other.Examples
SHOW PolyCatenate("The ","time ","is ",AC1)
"The time is 0"
This example uses a SHOW Command to demonstrate how the PolyCatenate( ) string Procedure combines four strings. The SNA AC1 is automatically coerced to a string.
SHOW PolyCatenate("Yours"," ","truly,")
"Yours truly,"
This example uses a SHOW Command to demonstrate how the PolyCatenate() string Procedure combines three string constants.
Action
PolyCatenate( ) first coerces all arguments to strings. Any number of arguments may be used. It then creates a string large enough to contain the result, and copies the argument strings into the result string one after the other. Any of the arguments can be a null string.
11. Right - Return a terminal substring.
Syntax ReturnString = Right(SourceString, MaxCount)Arguments
SourceString
- The source string to be used to create the substring. Required. Coerced to string. The argument must be Expression.MaxCount - The maximum number of characters to be used in the substring. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as the right MaxCount characters of SourceString.Example
SHOW Right("123456789",6)
"456789"
This example uses a SHOW Command to demonstrate how the right() string Procedure extracts the last 6 characters of the string "123456789".
Action
Right( ) coerces the first argument to a string, and the second to an integer. If MaxCount is less than 0, it is made equal to 0. Right( ) then creates a string of length equal to the smaller of MaxCount and the length of SourceString. The result string is then filled with the last MaxCount characters from SourceString.
12. String - Create string equivalent.
SyntaxReturnString = String( Datum )
Arguments
Datum
- The data item to be converted. Required. Coerced to string. The argument must be Expression.Return Value
ReturnString
- The string created as a result of converting Datum to its string equivalent.Example
SHOW String(12345)
"12345"
This example uses a SHOW Command to demonstrate how the string() string Procedure converts the integer constant 12345 to the string constant "12345".
Action
String( ) coerces the arguments a string, and returns a copy as the result. If the argument is already a string, it is not modified.
13. StringCompare - Compare two strings.
Syntax ReturnInteger = StringCompare( String1, String2 )Arguments
String1
- The first of two strings to be compared. Required. Coerced to string. The argument must be Expression.String2 - The second of two strings to be compared. Required. Coerced to string. The argument must be Expression.
Return Value
ReturnInteger
- Integer -1, 0, or 1 as String1 precedes, equals, or succeeds String2.Example
SHOW StringCompare("ABC","abc")
-1.0000000
This example uses a SHOW Command to demonstrate how the StringCompare( ) string Procedure compares the two string constants and returns the result of the comparison.
Action
StringCompare( ) coerces the first and second arguments to strings. It then compares them lexicographically.
If the two strings are identical, an integer 0 is returned. Otherwise the strings are compared character by character until a difference is detected.
If the first difference occurs because one string is shorter than the other, the shorter string is said to precede the longer one. If the shorter string is String1, -1 is returned. If the shorter string is String2, 1 is returned.
If the first difference occurs because the character from String1 precedes that from String2 in the ASCII collating sequence, String1 is said to precede String2, and -1 is returned. Otherwise, String2 is said to precede String1, and 1 is returned.
14. Substring- Return part of a string.
SyntaxReturnString = SubString( SourceString, Offset, MaxCount )
Arguments
SourceString
- The string to be used as the source of the substring. Required. Coerced to string. The argument must be Expression.Offset - The 1-relative offset in SourceString of the first character of the substring. Required. Coerced to integer. The argument must be Expression.
MaxCount - The maximum number of characters from SourceString to use in the substring. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnString
- The string created as a result of creating a copy of a substring derived from SourceString.Example
SHOW Substring("123456789",3,4)
"3456"
This example uses a SHOW Command to demonstrate how the substring() string Procedure copies 4 characters from the string constant "123456789" to form a new string.
Action
Substring( ) coerces the first argument to a string, and the second and third to integers. If the Offset argument is less than 1, it is set to 1. Substring ( ) then creates a string large enough to canteen the lesser of the MaxCount argument or the number of characters remaining after the offset in the source string. Substring( ) then copies the characters from the substring, if any, into the result string.
15. Trim - Remove leading and trailing white space.
SyntaxReturnString = Trim( SourceString )
Arguments
SourceString
- The string to be used as the source of characters. Required. Coerced to string. The argument must be Expression.Return Value
ReturnString
- The string created as a result of trimming blanks and tabs from SourceString.Example
SHOW Trim(" A B C ")
"A B C"
This example uses a SHOW Command to demonstrate how the Trim( ) string Procedure creates a new string by removing leading and trailing blanks from a string continuing them.
Action
Trim( ) coerces the arguments to a string. It then creates a string large enough to contain the result, and copies the source string into the result string, omitting leading and trailing blank or tab characters.
16. Uppercase - Convert string to upper case.
SyntaxReturnString = UpperCase( SourceString )
Arguments
SourceString
- The string to be converted. Required. Coerced to string. The argument must be Expression.Return Value
ReturnString
- The string created as a result of converting SourceString to upper case.Example
SHOW Uppercase("123 aBc")
"123 ABC"
This example uses a SHOW Command to demonstrate how the uppercase( ) string Procedure copies a string and converts the lower case letters to upper case.
Action
Uppercase( ) coerces the argument to a string, and creates a copy of the string. It then converts the lower case letters in the copy to upper case and returns it as the result string.
17. Value - Convert to numeric equivalent.
SyntaxReturnReal = Value( Datum )
Arguments
Datum
- The data item to be converted. Required. The argument must be Expression.Return Value
ReturnReal
- The double precision real numeric value equivalent to Datum. A real value.Example
SHOW Value("123.4")
123.4000000
This example uses a SHOW Command to demonstrate how the value( ) string Procedure converts the string "123.4" to its numeric value.
Action
Value( ) determines the data type of the argument. Integers or stings are converted to their real numeric equivalent, and returned. Real arguments are returned without modification.
18. Word - Extract a word from a string.
SyntaxReturnString = Word( SourceString, WordNumber )
Arguments
SourceString
- The string to be examined. Required. Coerced to string. The argument must be Expression.WordNumber - The 1-relative cardinal number of the word in SourceString to be returned. The argument must be Expression.
Return Value
ReturnString
- The string containing the word extracted from SourceString.Example
SHOW Word("My country ’tis of thee.",2)
"country"
This example uses a SHOW Command to demonstrate how the word( ) string Procedure extracts the second word of a source string.
Action
Word( ) coerces the first argument to a string, and the second to an integer. It then finds the word corresponding to the second argument, and creates a string large enough to contain it. Finally, it copies the characters of the word, if any, into the result string.
Words are consecutive printable characters other than tabs or blanks. If the corresponding word does not exist in the source string, a null string is returned.
The built-in GPSS World Library contains a number of Procedures for controlling Data Streams from within your own PLUS Procedures. Data Streams are discussed in Section 4.16. These can be used to read from or write to files or to store and access a large amount of data in memory.
You can invoke these procedures in place of using the corresponding GPSS Block. The library procedures allow you to do everything that the corresponding Blocks do with one exception: the PLUS library procedures do not support Replace Mode.
Open( DataStream, FileNameString ) - initialize a Data Stream.
Close( DataStream ) - terminate a Data Stream and retrieve its error code.
Read( DataStream) - retrieve a text line from a Data Stream.
Write( DataStream, String ) - pass a text line to a Data Stream.
Seek( DataStream, NewLinePosition ) - set the Current Line Position of a Data Stream and retrieve the previous Line Position.
1. Open - Initialize a Data Stream
You can use a Data Stream to read and write to a file, or
to maintain a set of directly accessible data in the memory of your
computer. open, close, read, write and seek operations exist both as GPSS
Blocks and as PLUS library procedures. You can perform complex file
input/output operations within your own PLUS Procedures or by using higher
level GPSS Block Entities, and you may mix the two modes. The Blocks are
discussed in Chapter 7.
Syntax
ReturnCode=Open( DataStream, FileNameString )
Arguments
DataStream
- The number of the new Data Stream to be opened. Required. Coerced to integer. The argument must be Expression.FileNameString - The name of the file to be written to. Required. Coerced to string. The argument must be Expression.
Return Value
ReturnCode
- A code indicating the success of the operation. Success is 0, otherwise an error occurred which is described by the value of the return code, as listed below.Example
Result = Open(2,"MYFILE.TXT");
In this example, the Open() Procedure creates the type of Data Stream known as an I/O Stream, and gives it number 2 for identification. If an error occurs during the Open, an error code is returned.
Action
The Open library procedure Block causes a Data Stream to be created, and sets the Current Line Position to 1.
The first argument must identify the Data Stream to be used. A Data Stream is a sequence of text lines used by a GPSS World simulation. Each Data Stream is identified by a unique number. There are 2 types of Data Stream:
1. Input/Output (I/O) Streams, and
2. In-Memory Streams.
The second argument is evaluated as a string. If it is a null string, an In-Memory Stream is created. Otherwise an I/O Stream is created, and the argument is presumed to be a file specification. If a path is not included in the file specification, it is assumed that the simulation directory is to be used.
A Data Stream is a sequence of text lines used by a GPSS World simulation. Each Data Stream is identified by a unique number, so that many can be processed at the same time within in a single simulation. Data Stream numbers are arbitrary positive integers, assigned by you.
If, when you Open() a file type Data Stream, you use a file name without a path, the directory of the Simulation Object is assumed to be the location of the file. When an existing file is found, it is completely loaded into virtual memory during the processing of the OPEN Block. If no file is found, it is assumed that you are creating one, and processing continues.
If the Data Stream has already been opened, the open operation concludes without raising an error condition.
If an error is detected, the error code is stored internally as well as being returned by the Procedure. A CLOSE Block can be used to retrieve a stored Error Code.
Data Streams are buffered in virtual memory. When an existing file is found by an open operation, it is completely loaded into virtual memory. If no file is found, it is assumed that you are creating one, and processing continues. After the open operation completes, all data is kept as part of the Simulation Object until the Data Stream is closed. Any changes to the data are returned to the file system only when the Data Stream is terminated by a CLOSE Block or a Close() library procedure.
Chapter 4 (4.16) contains a full discussion of Data Streams. The open operation can also be performed by an OPEN Block, described in Chapter 7, as well as the Open() PLUS library procedure, described here.
Return Codes
·
0 - No Errors.·
10 - Error. Filename too long. Data Stream not created.·
11 - Error. Error while reading an external file. Data Stream not created.·
12 - Error. Memory request was denied while trying to read an existing file. Data Stream not created.
2. Close - terminate a Data Stream and retrieves its error code.
Syntax ReturnCode=Close( DataStream )Arguments
DataStream
- The number of the new Data Stream to be opened. Required. Coerced to integer. The argument must be Expression.Return Value
ReturnCode
- A code indicating the success of the operation. Success is 0, otherwise an error occurred which is described by the value of the return code, as listed below. If an error occurred during a previous Open(), Read(), Write(), or Seek() operation, the original nonzero error code is returned, as described below.Example
Result = Close(2);
In this example, the Close() Procedure terminates the operation of Data Stream 2 and frees all the resources associated with it. If any error occurred in a previous operation involving Data Stream number 2, the original error code is returned. Otherwise a 0 value is returned.
Action
The Close library procedure shuts down a Data Stream and retrieves its error code.
The argument is evaluated numerically, truncated, and used as the entity number of the Data Stream. The result must be a positive integer.
Chapter 4 (4.16) contains a full discussion of Data Streams. The close operation can be performed by a CLOSE Block, described in Chapter 7, as well as the Close library procedure, described here.
Return Codes
·
0 - No Errors.·
10 - Open Error. Filename too long. Data Stream not created.·
11 - Open Error. Error while reading an external file. Data Stream not created.·
12 - Open Error. Memory request was denied while trying to read an existing file. Data Stream not created.·
21 - Read Error. A memory request was denied while trying to perform a read operation.
· 22 - Read Error. Data Stream has not been successfully opened.
·
31 - Write Error, A memory request was denied while trying toperform a Write operation.
·
32 - Write Error. Data Stream has not been successfully opened.·
41 - Close Error. An I/O Error prevented the file from being written to disk.·
43 - Close Error. Data Stream has not been successfully opened.·
51 - Seek Error. Data Stream has not been successfully opened.
3. Read - retrieve a text line from a Data Stream.
Syntax ReturnString=Read( DataStream )Arguments
DataStream
- The number of the new Data Stream to be opened. Required. Coerced to integer. The argument must be Expression.Return Value
ReturnString
- The string read from the Current Line of the Data Stream.Example
NextLine = Read(1);
In this example, the Read() Procedure retrieves a text line from Data Stream number 1 and places a copy in the User Variable named NextLine. If an error occurs, a null string is assigned to NextLine and an Error Code indicating the specific reason is stored internally, and can be retrieved by a Close operation. These values are listed under the Close Procedure, described above.
Action
The argument is evaluated numerically, truncated, and used as the Data Stream Entity number. This must be a positive integer.
If an error is detected, the error code is stored internally. A CLOSE Block or a Close() Procedure invocation can be used to retrieve the Error. Chapter 4 (4.16) contains a full discussion of Data Streams.
The text line is determined by the Current Line Position, a 1-relative line index associated with the Data Stream. During a Read operation the line indicated by the Current Line Position, even if the line is a null string, is returned. Then, the Current Line Position is incremented, i.e. move to the next line number. If there is no line to be read, a null string is returned without any error code being stored. A seek operation can be used to change the Current Line Position.
4. Write - pass a text line to a Data Stream.
Syntax ReturnCode=Write( DataStream,SourceString )Arguments
DataStream
- The number of the new Data Stream to be opened. Required. Coerced to integer. The argument must be Expression.SourceString - The sting to become the next line in the Data Stream. Required. Coerced to integer. The argument must be Expression.
Return Value
ReturnCode
- A code indicating the success of the operation. Success is 0, otherwise an error occurred which is described by the value of the return code, as listed below.Example
Result= Write(1,"New Line 20");
In this example, the Write() Procedure sends a text line to Data Stream number 1. If an error occurs, a nonzero code is returned and is also stored internally. The error codes are described below.
Action
The first argument is evaluated numerically, truncated, and used as the Data Stream Entity number. This must be a positive integer.
The second argument is evaluated as a string. The Write Procedure then:
1. Moves all text lines at, or after, the Current Line Position down one position.
2. If the Current Line Position is after the last text line, sets it to just after the last text line in the Data Stream.
3. Places a copy of the new text line at the Current Line Position.
4. Increments the Current Line Position.
If an error is detected, the error code is stored internally as well as being returned by the Procedure. A Close() Procedure invocation can be used to retrieve a stored Error Code.
Chapter 4 (4.16) contains a full discussion of Data Streams. WRITE Blocks support an additional mode of operation called "Replace Mode". It is not supported by the Write() library procedure.
Error Codes
·
0 - No Errors.·
31 - Error, A memory request was denied while trying to perform a write operation.·
32 - Error. Data Stream has not been successfully opened.
5. Seek - set the Current Line Position of a Data Stream.
Syntax PreviousLinePosition=Seek( DataStream,NewLinePosition )Arguments
DataStream
- The number of the new Data Stream to be opened. Required. Coerced to integer. The argument must be Expression.NewLinePosition - The new 1-relative value of the Current Line Position of the Data Stream.
Return Value
PreviousLinePosition
- The value of the Current Line Position of the Data Stream before the Seek operation is executed.Example
LastPosition = Seek(1,22);
In this example, the Current Line Pointer of the Data Stream is changed to 22.
Action
Each Data Stream has a Current Line Position. This is a 1-relative index to the next line position to be read or written. The first argument is evaluated numerically, truncated, and used as the Data Stream Entity number. The second argument is evaluated numerically, truncated, and used as the new Current Line Position of the Data Stream. Both must be positive integers.
If an error is detected, the error code is stored internally. A Close() Procedure invocation can be used later to retrieve the Error Code. These values are listed under the Close Procedure, described above.
The built-in GPSS World Library contains a number of Procedures for invoking functions that exist in external executable files including Dynamic Link Libraries, known as DLLs. You can use the appropriate Procedure, as discussed below, to invoke third party functions in separate executable files that observe the standard CDECL programming protocol. They may optionally return an integer return code, and they may optionally take an integer, char * (string), or double (real) argument.
All PLUS Dynamic Call Procedures require you to name both the executable file (EXE or DLL) and the function that is to be invoked. Further, you must match the PLUS Procedure to the requirements of the target function. If the function requires an integer argument you must use the Call_Integer() Procedure. Similarly, use the Call_String() or the Call_Real() to invoke a DLL function requiring a string (i.e. char *) or a real (i.e. double) argument. Use the Call() Procedure to invoke a function with no (i.e. void) argument. The choice of PLUS Procedure allows the argument to be coerced to the appropriate data type required by the target function.
If the external function returns an integer return code, the PLUS Call Procedure will provide it as the result of the PLUS Procedure call. Otherwise, the resulting value will be meaningless. Clearly, you must know the detailed characteristics of the function you are calling.
The Dynamic Call Procedures are:
ReturnCode = Call( ExecutableFileName, FunctionName ) - Invoke an external CDECL function with no ( i.e. void) arguments.
ReturnCode = Call_Integer( ExecutableFileName, FunctionName, Argument) - Invoke an external CDECL function with a single integer argument.
ReturnCode =
Call_String( ExecutableFileName, FunctionName, Argument ) - Invoke an external CDECL function with a single string (i.e. char *) argument.ReturnCode = Call_Real( ExecutableFileName, FunctionName, Argument ) - Invoke an external CDECL function with a single real (i.e. double) argument.
The Search for your DLL or EXE File
The first argument in all PLUS Dynamic Calls is a string naming the executable module (either a .DLL or .EXE file) containing the target function. If the string specifies a path, only that path is searched. When specifying a path, be sure to use backslashes (\), not forward slashes (/). If a path is not specified and the filename extension is omitted, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the search for the module proceeds in the following sequence:
1. The directory from which the application loaded. i.e. the GPSS World Module Directory.
2. The current directory.
3. The Windows system directory.
4. The Windows directory.
5. The directories that are listed in the PATH environment variable.
The second argument in the Call invocation is used to identify the target function. You must specify the same name exported in the named DLL or EXE file, including appended underscore, if any. If you do not include a required underscore in the function name, the Call Procedure will fail.
This chapter contains the information you need to use the theoretical probability distributions in the Procedure Library. Empirical distributions, on the other hand, are normally created by using the GPSS FUNCTION Command, using D or C type random Functions. This is discussed in Chapter 6. As other alternatives, it is easy to create your own random variate generators by defining your own PLUS Procedures, or to read empirical data from a file.
Over 20 built in probability distributions are included in the Procedure Library. These distributions are applicable to a wide range of practical situations. [For an excellent detailed discussion, see Law, A.M. and W.D. Kelton: Simulation Modeling and Analysis, 2nd Ed., McGraw-Hill, New York (1991)].
Each Procedure call to a probability distribution requires that you specify a stream argument. In this position, you are to assert an Expression that evaluates to a Random Number Generator Entity number. Random Number Generator Entities are created, as needed, so you need not predefine them. Several Random Number Generators are used by GPSS World for GENERATE, ADVANCE, and TRANSFER blocks. These are specified in the "Random" page of the Model Settings notebook. This is discussed in Chapter 2.
Most of the probability distributions are specified by parameters that select from a family of functions. Procedure arguments denoted locate, scale, and shape are often used for this purpose. The locate argument acts like a post-hoc adder, that is applied after the draw from the distribution. It allows you to move the distribution horizontally, to any position on the x axis. The scale and shape arguments, if used, select a member from the family of distributions.
The built-in Procedure Library contains the following probability distributions:
·
Beta · LogLaplace·
Binomial · LogLogistic·
Discrete Uniform · LogNormal·
Exponential · Negative Binomial·
Extreme Value A · Normal·
Extreme Value B · Pareto·
Gamma · Pearson Type V·
Geometric · Pearson Type VI·
Inverse Gaussian · Poisson·
Inverse Weibull · Triangular·
Laplace · Uniform·
Logistic · Weibull
1. Beta
Syntax
Real
= BETA( Stream, Min, Max, Shape1, Shape2 )Arguments
Stream
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Min- The smallest sample to be generated. Required. Coerced to real. Must be less than max. The argument must be Expression.
Max- The largest sample to be generated. Required. Coerced to real. Must be greater than min. The argument must be Expression.
Shape1 - The first selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Shape2 - The second selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8—1. The Beta Distribution
Notes
The Beta Distribution degenerates to the Uniform when the Shape1 and Shape2 arguments are 1. That is, Beta( Stream, Min, Max, 1, 1 ) is distributed as Uniform( Stream, Min, Max ).
Beta( Stream, Min, Max, 1, 2 ) is a left triangle; Beta( Stream, Min, Max, 2, 1) is a right triangle.
2. Binomial
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Integer
= BINOMIAL( Stream, TrialCount, Probability )Arguments
Stream
TrialCount - The number of Bernoulli trials in a sample. Required. Coerced to integer. Must be strictly positive. The argument must be Expression.
Probability - The success probability of a Bernoulli trial. Must be between 0 and 1. Required. Coerced to real. The argument must be Expression.
Return Value
Integer
- The integer value generated as a single instance of the probability distribution.
Probability Mass Function
Figure 8
—2. The Binomial Distribution
3. Discrete Uniform
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Integer
= DUNIFORM( Stream, Min, Max )Arguments
Stream
Min- The smallest sample to be generated. Required. Coerced to integer. Must be less than or equal to max. The argument must be Expression.
Max- The largest sample to be generated. Required. Coerced to integer. Must be greater than or equal to min. The argument must be Expression.
Return Value
Integer
- The integer value generated as a single instance of the probability distribution.
Probability Mass Function
Figure 8
—3. The Discrete Uniform Distribution
4. Exponential
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= EXPONENTIAL( Stream, Locate, Scale )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—4. The Exponential Distribution
Notes
The Weibull Distribution degenerates to the Exponential when the shape argument is 1. That is, Weibull( Stream, Locate, Scale, 1 ) is distributed as Exponential( Stream, Locate, Scale ).
The Gamma Distribution degenerates to the Exponential when the shape argument is 1. That is, Gamma( Stream, Locate, Scale, 1 ) is distributed as Exponential( Stream, Locate, Scale ).
5. Extreme Value A
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= EXTVALA( Stream, Locate, Scale )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—5. The Extreme Value A Distribution
6. Extreme Value B
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= EXTVALB( Stream, Locate, Scale )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—6. The Extreme Value B Distribution
7. Gamma
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= GAMMA( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—7. The Gamma Distribution
Notes
The Gamma Distribution degenerates to the Exponential when the shape argument is 1. That is, Gamma( Stream, Locate, Scale, 1 ) is distributed as Exponential( Stream, Locate, Shape ).
For positive integer m, Gamma( Stream, 0, Scale, m ) is distributed as the m-Erlang(Scale) distribution.
8. Geometric
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Integer
= GEOMETRIC(Stream, Probability)Arguments
Stream
Probability - The probability of success in each Bernoulli trial. Must be between 0 and 1. Required. Coerced to real. The argument must be Expression.
Return Value
Integer
- The integer value generated as a single instance of the probability distribution.
Probability Mass Function
Figure 8
—8. The Geometric Distribution
9. Inverse Gaussian
Syntax
Real
= INVGAUSS(Stream,Locate,Scale,Shape )Arguments
Stream
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—9. The Inverse Gaussian Distribution
10. Inverse Weibull
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= INVWEIBULL( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—10. The Inverse Weibull Distribution
11. Laplace
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= LAPLACE( Stream, Locate, Scale )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—11. The Laplace Distribution
12. Logistic
Syntax
Real
= LOGISTIC( Stream, Locate, Scale )Arguments
Stream
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—12. The Logistic Distribution
13. LogLaplace
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= LOGLAPLACE( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
14. LogLogistic
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= LOGLOGIS( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.15. LogNormal
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= LOGNORMAL( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—15. The Lognormal Distribution
16. Negative Binomial
Syntax
Integer
= NEGBINOM( Stream,SuccessCount,Probability)Arguments
Stream
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.
SuccessCount - The number of successful Bernoulli trials required before returning the failure count. Required. Coerced to integer. Must be strictly positive. The argument must be Expression.
Probability - The success probability of a Bernoulli trial. Must be between 0 and 1. Required. Coerced to real. The argument must be Expression.
Return Value
Integer
- The integer value generated as a single instance of the probability distribution.
Probability Mass Function
Figure 8
—16. The Negative Binomial Distribution
Notes
The Negative Binomial Distribution degenerates to the Geometric when the SuccessCount argument is 1. That is, NegBinom( Stream, 1, Probability ) is distributed as Geometric( Stream, Probability ).
17. Normal
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= NORMAL( Stream, Mean, StdDev )Arguments
Stream
Mean - The mean value of the distribution. Required. Coerced to real. The argument must be Expression.
StdDev - The standard deviation of the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—17. The Normal Distribution
18. Pareto
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= PARETO( Stream, Locate, Scale )Arguments
Stream
Locate - The shift value used to position the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—18. The Pareto Distribution
19. Pearson Type V
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= PEARSON5( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—19. The Pearson Type V Distribution
20. Pearson Type VI
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= PEARSON6( Stream, Locate, Scale, Shape1, Shape2 )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape1 - The first selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Shape2 - The second selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—20. The Pearson Type VI Distribution
21. Poisson
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Integer
= POISSON( Stream, Mean )Arguments
Stream
Mean - The mean number of events to occur. Required. Must be strictly positive. Coerced to real. The argument must be Expression.
Return Value
Integer
- The integer value generated as a single instance of the probability distribution.
Probability Mass Function
Figure 8
—21. The Poisson Distribution
22. Triangular
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= TRIANGULAR( Stream, Min, Max, Mode )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Min - The smallest value to be drawn from the distribution. Must be less than mode. Required. Coerced to real. The argument must be Expression.
Max - The largest value to be drawn from the distribution. Must be greater than mode. Required. Coerced to real. The argument must be Expression.
Mode - The most frequent value of the distribution. Must be greater than min and less than max. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—22. The Triangular Distribution
Notes
"Right" triangular distributions can be generated as Beta distributions.
23. Uniform
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= UNIFORM( Stream, Min, Max )Arguments
Stream
Min - The smallest value to be drawn from the distribution. Must be less than max. Required. Coerced to real. The argument must be Expression.
Max - The largest value to be drawn from the distribution. Must be greater than min. Required. Coerced to real. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.Probability Density Function
Figure 8
—23. The Uniform Distribution
Notes
The Beta Distribution degenerates to the Uniform when the shape arguments are 1. That is, Beta( Stream, Min, Max, 1, 1 ) is distributed as Uniform( Stream, Min, Max ).
24. Weibull
Syntax
- The random number generator entity number. Required. Coerced to integer. Must be greater than or equal to 1. The argument must be Expression.Real
= WEIBULL( Stream, Locate, Scale, Shape )Arguments
Stream
Locate - The shift value used to position the distribution. Required. Coerced to real. The argument must be Expression.
Scale - The compression value used to expand or contract the distribution. Must be strictly positive. Required. Coerced to real. The argument must be Expression.
Shape - The selection value used to choose from a family of shapes. Required. Coerced to real. Must be strictly positive. The argument must be Expression.
Return Value
Real
- The real value generated as a single instance of the probability distribution.
Probability Density Function
Figure 8
—24. The Weibull Distribution
Notes
The Weibull Distribution degenerates to the Exponential when the shape argument is 1. That is, Weibull( stream, Locate, Scale, 1 ) is distributed as Exponential( Stream, Locate, Scale ).
Weibull( Stream, Locate, Scale, 2 ) is known as the Rayleigh distribution.