gpss_manual

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.

This chapter contains reference information on the PLUS language, and on the built-in Procedure Libraries you can access through it. You cannot use PLUS to access

external files. (Use Data Streams for this purpose.)

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.

8.1. Defining PLUS Procedures

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.

8.2. The Language

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.

8.2.1. The Character Set

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 [^] is also considered as an operator.

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.

8.2.2. Names

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

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.

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.

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.

8.2.3. Expressions

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.

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

1. String Constants, such as "A stitch in time ...". 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

Array1[ P$Part, X$Order_Index+20 ]. Matrix elements must be

Name [ ExpressionList ] . The expression List can contain from 1 to 6

expressions, corresponding to the dimensions of the matrix. Each can vary in complexity from a simple integer to a highly complex PLUS expression.

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 #, not * (which is the indirect

addressing operator within System Numeric Attributes). All arithmetic operators coerce string operands to numeric values.

TO DO

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 Expression

4 # 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 which 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 which 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 / Settings

then 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.1e3 in scientific notation.

Special rules apply when a simulation is run in GPSS/PC Compatibility Mode. This are

For full examples of GPSS World Models using PLUS Routines, see the PLUS

PRIMER in Chapter 17 of the GPSS World Tutorial Manual.

1. Assignment Statement

Syntax

LValue = 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

Syntax

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

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.

4. EXPERIMENT Statement

Syntax

EXPERIMENT Name ( ArgumentList ) Statement

Name - A user-defined Procedure Name. Must be 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.