CA2122182A1 - Method for rapid prototyping of programming problems - Google Patents

Abstract

A METHOD FOR RAPID PROTOTYPING OF PROGRAMMING
PROBLEMS

ABSTRACT
Two major Forth extensions provide high-level sup-port for building rapid prototypes for systems. These extensions form distinct language vocabularies available in the Forth environment. One is a Finite State Machine Language, named FSML, and the other is an object oriented language, named 200L. Using these extension and the in-herent expandability of the Forth language, a prototype can be rapidly created. The modeling method requires four steps. First, using 200L, the system is described as a set of objects. At least one of the objects must be a controlling object and so identified. Second, using FSML, the controlling object is described as a finite state machine. Third, the system's operation is ex-pressed as a collection of one or more finite state ma-chines. Each finite state machine type is defined with a unique machine type name. Any number of instances of a finite state machine type can be dynamically created at execution time. Fourth, communication is allowed between the finite state machines.

Description

-- 21221~2 " ~

A METHOD FOR RAPID PROTOTYPING OF PROGRAMMING

PROBLEMS

' FIELD OF THE INVENTION
¦ The present invention relates to programming of computer systems. More specifically, the present inven-tion is a method of quickly implementing programming ideas into actual test code that can be used to test basic assumptions about the programming idea.

Background of the Invention To minimize risks and gain insight, most customers and vendors are cooperatively building prototypes and field trials, starting with simpler more restricted I capabilities and gradually adding capabilities in phased j steps. This can be done in stages, starting with ! 15 software-only simulations, followed by hardware/software } prototypes leading to the design refinements that can later be applied to a commercial system development with greatly reduced risk of unexpected and costly problems.
Software simulation of complex systems requires 20 flexible software tools that can represent the logical systems design elements in an executable form, i.e, a Rapid Prototype. The tools are used to build a logical prototype of the system being studied. There are several kinds of simulation possible. For logical analysis of 25 system models and protocols, a logical execution model ` works best. A statistical model and other mathematical ; models might be used for subsequent performance and reliability analysis.
` The tools should support rapid creation of design '1 30 elements that represent the level of logic being simu-, lated. The prototype is recursively refined and expanded to implement the model in increasingly greater detail.
This process quickly leads to deep insight about the model and problems as they are discovered.
To develop a rapid prototype, the tools should:
., --1 ., ~i :

- 2122~82 1) Minimize the conceptual distance between the logical model and the implementation;
i 2) Support logical representation at any level of detail without limitations imposed by resource of language ,i constraints;
~il 3) Retrain flexibility during all phases of development; and ~1 ~ 10 4) Provide an interactive user interface.
~' ~ This arrangement can best be described as a spiral q development strategy. One way to view the spiral is to picture a problem domain as a wheel with radial spokes defining sectors that represent parts of the problem.
Traversing a spiral, beginning at the center of the wheel, one encounters a small piece of each part of the problem. With each successive traversal of the spiral, the radius grows so that the path becomes longer and the level of detail, represented by the areas of the circum-scribed sectors, is increased. This process allows re-peated evaluations over the full scope of the problem, each time with more detail as design choices are simu-;~ lated with greater precision.
Prior to the present invention, a programmer wanting to test ideas or control systems had to expend a great ~ deal of time creating a computer model on which the prob-*1 lem could be simulated. Before the programmer could ~ begin testing any of the underlying assumptions, the :~ model needed to be nearly complete. This required that . 30 many of the detailed decisions and associated coding be in place. The present invention provides a method to rapidly start testing high level design assumptions even i prior to a detailed understanding of the low level 'i responses.
Therefore it is the objective of the present inven-~` tion to provide a method to rapidly reduce programming 'i -2-,, ideas and concepts into a working model whereby the - programming ideas and concepts can be tested at a high level.

Summary of the Invention In order to accomplish the objective of the present invention there is provided method for allowing a com-puter system to simulate a system. The invention is best j described as four steps. First the system is described 3 as a set of objects. At least one of the objects must be a controlling object and so identified. Second, the con-trolling object is described as a finite state machine.
Third, express the system operation as a collection of , one or more finite state machines. Create as many finite state machines as needed. These finite state machines can be statically defined with unique machine names. They can also be dynamically created at runtime, using the con-trolling finite state machine as the prototype. Forth, allowing communication between the finite state machines.
. ~

Description of the Drawings ~i 20 A better understanding of the invention may be had from the consideration of the following detailed descrip-tion taken in conjunction with the accompanying drawings, in which:
FIG. 1 is a high level block diagram showing the ' 25 layers of the present invention.
~l FIG. 2 is a pictorial representation of memory usage by the C4TH primitives + and swap.
FIG. 3 is a pictorial representation of memory usage by a C4TH typical thread.
FIG. 4 is a pictorial representation of memory usage by a more complicated C4TH thread.
FIG. 5 is a pictorial representation of memory usage 1 by a simple C4TH data word.
; FIG. 6 is a pictorial representation of memory usage , 35 by the C4TH doer word.
., ~ --3--:

, FIG. 7 is a pictorial representation of memory usage by 200L for a static named object (SN0).
FIG. 8 is a pictorial representation of data struc-ture built by the word method in 200L.
i 5 FIG. 9 is an example of data structure built by the word method: in 200L.
FIG. 10 is a pictorial representation of memory usage by a 200L descriptor.
FIG. 11 is a pictorial representation of memory usage by 200L as a result of the execution of short:
+seedl.
FIG. 12 is a pictorial representation of memory l usage by 200L as a result of the execution of m:.
3 FIG. 13 is a pictorial representation of memory :t 15 usage by 200L.
FIG. 14 is a pictorial representation of memory usage by FSML for the keyword input.
FIG. 15 is a pictorial representation of memory usage by FSML for the keyword input.
FIG. 16 is a pictorial representation of memory usage by FSML for create-timer timerl.
j FIG. 17 is a pictorial representation of memory , usage by FSML showing a part of the thread for machine i ml.
FIG. 18 is a pictorial representation of partial memory usage by FSML when creating states.
FIG. 19 is a pictorial representation of partial s memory usage by FSML when creating state S0.
'i FIG. 20 is a pictorial representation of memory usage by FSML once state S0 is created.
FIG. 21 is a pictorial representation of memory usage by FSML for the word }.
~i FIG. 22 is a pictorial representation of memory usage by FSML for the word }.
FIG. 23 is a pictorial representation of memory usage by FSML showing the format of the "input" message.
~ FIG. 2~ shows a rapid prototype for a basic call ii; model.
;~ FIG. 25 shows an intelligent network environment.
~i -4-; t .'' : Description of the Preferred Embodiment Referring to FIG. 1, at the lowest level, a Forth language nucleus is used. This particular implementation of Forth is in C to provide portability to a wide variety of host environments. Several properties of the Forth language have proven to be very important factors in minimizing the effort to build a rapid prototype.
1) Forth inherently provides an interac-tive user interface.

2) Forth is inherently an extendible lan-guage. New words added to the dic-tionary operate in an identical fash-ion as native Forth words. This makes it easy to create high-level, applica-tion-oriented language sets above the Forth nucleus to minimize the concep-tual distance between the problem domain ~the logical model) and the implementation language.

3) The Forth system provides efficient support for multi-task operations internal to an application.

4) The Forth system contains a wide vari-;~ ety of internal development tools that ~ 25 support testing and debugging ;~ operations.
.

5) Large complex problem domains can be implemented in great detail without ~ restrictions due to resource exhaus-s~, 30 tion, even on relatively modest host ~ platforms.
51l Two major Forth extensions provide high-level sup-'~ port for building rapid prototypes for real-time control systems such as telecommunication switching systems.
These extensions form distinct language vocabularies ~, available in the Forth environment. One is a Finite State Machine Language, named FSML, and the other is an object oriented language, named 200L.
Finite State Machine Language - FSML
; 5 FSML supports definition of an arbitrary set of com-municatingl finite state machines. Each Finite State Machine (FSM) runs as a separate task and can establish static or dynamic communication bindings with other FSMs.
FSML syntax is simple. Referring to Table 1, each FSM is defined as a list of states. Under each state is a list of inputs that are valid for that state. Following each input is a next-state and action list (output) to be exe-cuted when the FSM receives the input while in that state. Inputs are programmer-defined tokens sent to an FSM via messages. Messages may contain any additional parameters needed by the application. FSML also supports the concept of sub-machines in which inputs are synchro-nously processed in the task-space of a parent FSM. This extension provides a natural expression of more complex finite state machines in which there may be states and sub-states. This has proven very practical in supporting solutions to real-world problems without incurring prob-lems of un-bounded state expansion.
By way of an example, a Finite State Machine (FSM) ` 25 is a specialized controlling object or structure that can be used to define the action of a system or subsystem. As stated above, an FSM is defined by it's states, input -next-state transition pairs, and action routines.
., __________________________________________________________________________ machine A

. state 1 ~', input next-state action routine _______ __________ ____________________ :
`1 3 5 Input Xstate 2 { perform action 1 ]
~'i Input Ystate 1 ~ { perform action 2 J Input Zstate 2 { perform action 3 or-else state 1 { perform action 7 J

, . .

2122~82 state 2 input next-state action routine _______ __________ ____________________ Input X state 2 I perform action 4 }
Input Y state 1 { perform action 5 ~
Input W state 1 I perform action 6 }
or-else state 2 ~ perform action 7 1 i 1 start-state state 1 ----------------------------_____________________________ This FSM has 2 states, 1 and 2. When instantiated, it : starts out in state 1. If this FSM receives an input X, it changes to state 2 and performs action routine 1. Each state has an or-else clause to handle unknown inputs.
The following is an example of how a simple Voice Mail (VM) system could be modeled using an FSM. This example will be used as the steps involved in designing a model are ex-plained below.
- ____________________________________ machine VoiceMailbox state Choose_VM_Option input next-state action routine ; ---- --------____________ : 25 Buttonl Play_Messages ¦ retrieve messages l Button2 Send_Message ~ get list of mailboxes and prompt for ~. mailbox # ) ;~ Button3 Quit_VM ( no action required ~
"! VM Message Choose_VM_Option ~ store incoming message from other VM
mailbox }
Message Choose_VM_Option { store callers message ~
.: ~ or-else Choose_VM_Option ( prompt user "Invalid Input!" }

~ _7-:

.

2122~2 state Play_Messages input next-state action routine Buttonl Play_Messages ~ tag each message as old after played }
Button2 Choose_Vh_Option ~ erase all tagged messages ) or-else Play_Messages ~ prompt user "Invalid Input!"

state Send_Message 0 Mess_to Send Send Mes3age ~ save mes3age to send 1 Send Choose_VM_Option { send VM_Mes3age to target VoiceMailbox ) or-else Send_Mes3age ~ prompt user "Invalid Input!"

15 state Quit_VM
input next-state action routine _______ _____________ ____________________ Buttonl Choose_VM_Option ~ exit system but reinitialize for next access ) or-else Choose_VM_Option ~ abort quit, no action required ) start-state Choose_VM_Optlon From this description, it is apparent that this machine has 4 states. The last line (start-state Choose_VM_Option) indicates that the starting state is the Choose_~M_Option state. Once in this state, the transition pairs determine both the next state and action taken for any given input. For example, if Buttonl is pressed, the FSM changes to state Play_Messages and the action routine causes the messages to be retrieved. The other states and transition pairs operate in a similar manor.
During the first few passes, the action routine may do nothing more than return a message that the desired action occurred without actually performing any action at ~-i all. This allows the designer to implement the FSM.
Once the FSM is functioning, the actions routines can , then be defined in greater detail. As stated above, the action routines may contain FSM (sub-machines) as well.
Tables 7 and 8 provide definitions for the FSML and FMTOS words along with a few screens for the more compli-cated words.
Object Oriented Language - 200L
The other major extension to the forth operating system is 200L. 200L supports the object classes with the following language characteristics:
10 1. Information Hiding Instance data is normally private and accessible only indirectly via an object's methods.
2. Polymorphism Method names may be common across classes, with specific functionality bound to each class.
3. Multiple-Inheritance Object classes all inherit the methods of the base class, CLASSO, and can comprise elements of other classes whose specific methods are automatically inherited.
4. Early Ar.d Late Binding Objects may be instantiated at compile time and be created as "static named objects". Both the class and the methods are bound at compile time (early binding).
Objects may be instantiated at execution time (dynamic objects). When a method is to be applied ("sent to") an object, either the method index or the class descriptor or both may be supplied at _g_ 21~2182 execution time (late binding).
Object classes provide methods for creating objects that are named, static instances of a class or as dy-5 namic, un-named instances of a class. 200L provides convenient access to un-named objects via named Object Handles which can be temporarily attached to dynamic objects, allowing them to be referenced by the Object Handle name as if they were named static objects. 200L
10 supports object association via an alias method which allows an object's instance data to define a kind of pointer to another object, still inheriting all that object's methods as if the object itself were included.
In 200L, there are two kinds of objects; "classes"
15 and "objects". A class is a specialized kind of object which may be "instantiated" to create specific objects whose form and operations are determined by the class definition. All class objects are members of the underly-? ing 200L base class, called "CLASSO:". 200L classes can ~ 20 inherit the instance variables and methods of other , ~ classes by directly incorporating objects from those ¦ other classes within the class instance data definition.
An instance of a class is created by using the MAKE
method. The M~KE method will allocate the required amount 25 of memory for all the instance data of the class, includ-~ ing the instance data that comprises objects of other ;~i classes. In other words, instances of inherited classes will be created at the same time an instance of the class is created.
200L syntax is consistent with the underlying Forth -l language suffix notation in which operation verbs apply f' ' to the contents of the parameter stack.
~ <parameters> <object name> <method name>
;' For example, "3 5 +" will leave "8" on the stack.
Operation verbs for 200L objects are called methods. A
I "method" is the object-oriented terminology for a func-tion or procedure.
Object oriented design encourages a change in mind-set from thinking of data and procedures that operate ;, , 21221~2 upon the data as separate entities to the viewpoint that a program consists only of objects which have various behaviors, determined by the methods supported by each object. The objects are then viewed as building blocks to be combined in many ways to build programs that accom-plish the desired tasks.
Accordingly, an object named X in 200L could be printed by the statement:
X PRINT, where PRINT is a method defined for the object class of object X.
200L class data definitions allow a wide variety of primitive data types, including signed and unsigned vari-ables of various sizes, structures, unions, and arrays.
These elements may be combined as needed for the applica-tions, creating arrays of structures of variables, or structures including arrays of elements, for example.
Instance data may include objects of other classes and inherit all the methods applicable to those objects. Of course, these may also be arranged in structures and arrays, as required. 200L class methods and instance data may be declared as private or public. Object in-stance data is normally private, and cannot be referenced outside the object, and must be accessed only by the methods defined for its class.
The M~KE method is used only for static named objects. For example, to make an instance of a class named classx: and name the instance X the following coding would be used:
classx: MAKE X
Although not required, by convention all classes in 200L have names ending with a colon. Another convention ls to use upper case (or mostly upper case) letters in method names. There is no particular convention for object names.
There is no UNM~KE for static named objects. They are created at compile time and remain persistent as long as the load exists.

'' ' ''. ',, ~' '~ ' ' ;, . ..

The DM~KE method is used to create dynamic in-stances of a class. Dynamic objects do not have names.
The DM~KE method returns an object address on the parame-ter stack. It is up to the programmer to manage the ad-dresses of dynamic objects. 200L provides the ability todefine named object handles which can be assigned the class descriptor and the object address of any dynamic object. Typically, object handles are associated perma-nently with a particular class descriptor and then as-signed different object addresses dynamically as thesystem operates. The object handles allow dynamic objects to be referenced by the object handle name in the same way a static named object can be referenced by its name.
The only difference is that the object handle must be attached to the object address at execution time as it is used to reference different instances of objects of its class.
There is a DUNMAKE method that can be used to de-stroy dynamic objects and return their memory resources to the system.
The following small example shows how to create an object handle and attach it to a dynamic instance of classx:
object-handle: X ( create~ a ~tatic object handle entity called X ) cla3sx: a~sign-type: X ( initializes X with the clas~x: type descriptor ) clas~x: DMAKE become~: X ( create~ a dynamic in~tance of cla~x: and ( attaches it to the object handle X
.

X DUNMAKE ( unmake~ the dynamic in~tance of clas~x: ) O becomeq: X ( reset~ the object addre~ of X to zero After all the discussion about instantiating classes to create objects, the user will still be unpre-pared to use this information if he or she doesn't know how to define a class in the first place.
A class consists of a definition of the "instance variables" and the class-specific definition of the methods that operate upon those variables. The class ... . . . . . ... . . ..

"instance variables" are defined as a structure of the data elements that act as a template for the data to be created for each instance of the class. The class in-stance data structure defines an organization of data elements of several kinds:
primitive data elements: byte, ubyte, short, ushort, long, ulong, ... etc.
object class elements: objects of other 200L classes . object class alias elements: typed pointers to objects of other 200L
classes ,.
, . arrays of any of the above elements ; . unions of any of the above elements Example class definition from Intelligent Network 1 application:
class: CsID:
?method: CLONE
. ?method: $ASN
private:
\ CLASS DATA
\ ==================== =
ulong: +CsID
,~ \ ========================
dup define-memQ CsID-memQ
public:
m: DMAKE ( -- 'obj ) CsID-memQ mget ;m i m: DUNMAKE t 'obj -- ) .UNMAKE? iftrue cr ." UNMAKING CsID INSTANCE " oa ADDR d. cr ifend oa ADDR CELL - @ [ ' CsID-memQ >body ] literal = if oa ADDR mput then ;m m: !! ( val -- ) oa +CsID !! ;m m: @Q ( -- val ) oa +C`qID @@ ;m m: PRINT ( -- ) cr ." CsID= " oa +CsID @@ d. ;m ' -13-, i 2122~8~
m: CLONE ( -- 'obj ) CsID: DMAKE ( 'obj ) oa +C~ID @@ ( 'obj CsID ) over men~er-of: CsID: tCsID !! ;m m: $AsN ( Token -- ) 1 needed drop " csID " AB
oa +CsID @~ x,~>AB
nl>>AB
;m ;class The class: and ;class words bracket the class definition.
The .~method: word is used to pre-define the method names. This is a conditional definition, only if the name has not already been defined as a method before. Method names are associated with an arbitrary system index which is used to link the definition of the method for a spe-cific class in the class descriptor table compiled uniquely for each class definition. Method names are all placed into the OOL vocabulary to avoid confli~ts with user defined words in other vocabularies. The ?method:
definitions do not have to be within the class: and ;class words. There is an alternative method: word that will redefine the word with a new index, but this would be an unusual thing to do.
Note that .~method: definitions were only used in this class definition for the CLONE and SASN methods, because the other method names are all predefined within 200L itself. Method names are global, but must be bound to each specific class. The specific definition within a class is provided by the m: definitions. Note that other generic methods, such as DUMP, LIST-METHODS, SIZE, etc.
may also be applied to instances of this class, but have not been redefined specifically for this class. These will inherit the CLASS0: definitions provided within 200L.
The user may provide a new definition of any of the CLASS0: methods within a new class, and the new defini-tion will be used on objects of this class. The new 21221~2 ., definition can reference the CLASSO: definition of the method as part of the new definition, if desired.
For example, if the user wanted to redefine the DUMP method for the example class above so that it printed out an additional string before dumping the object with the CLASSO: dump, the new definition could be coded:
m: DUMP ( -- ) cr 20 spaces . " DUMP OF CsID OBJECT: "
[ also (OOL) ] oa DUMP
;m The private: word is used to declare the following definitions to be hidden from access from anywhere out-side the class definition. The instance data definitions are typically made private. The names of instance data elements, such as +CsID in the example, are also a form of method. These names return the offset of the data ele-ment from the top of the object's address space. The public: word makes following definitions accessible out-side the object. The private: and public: mode words canbe interspersed in the class definition as desired to control the information hiding for any methods.
By convention, instance data element names begin with "+" to emphasize the offset they return must be added to the object address. This shows up within the m:
definitions where the object address operator "oa" must be used for referencing the instance data. The oa opera-tor satisfies the compile time requirement of providing the class descriptor needed when compiling a reference to ¦ 30 a data element, and at execution time it provides the object's base address to which the element's offset is automatically added for element references.
Tables 2 to 5 list the added forth words for 200L.
Table 6 provides a definition for the 200L words along 1 35 with a few screens for the more complicated words.
I Description Of Inner-Workings Of 200L And FSML
¦ Both FSML and 200L may be thought of as special pur-pose compilers, extending the syntactic constructs which ~ -15-can be handled in the FORTH environment: the FSML com-piler supporting those constructs associated with a Finite State Machine Language and the 200L compiler sup-porting those constructs associated with Object Oriented Programming.
In order to understand the implementation of these two special purpose compilers, it is first necessary to have a basic understanding of the compilation and inter-pretation process supported by the underlying C4TH sys-tem. The C4TH implementation provides for three basictypes of words: primitives, threads and created words.
A primitive word is one whose behavior is provided by a single C function which is called any time the primitive is executed. There is a one to one relation between the primitive and the C function. The implemen-tation of two primltives, + and swap, is illustrated in Figure 2. The + primitive takes the top two items on the parameters stack, adds them together, and leaves the re-sult on the parameter stack. The swap primitive takes the top two items on the parameter stack and interchanges their relative positions -- the top item becomes the sec-ond item and the previously second item is now on top;
i.e., it sw~ps one for the other.
The implementation consists of two portions, a header and the word, which are linked together. The main content of the header is a string of ASCII characters giving the symbolic name of the word. When the user types in the name of a word to be executed or compiled, the headers are searched to find one matching the name typed in by the user, and once a match is found, a pointer in the header indicates where the word itself is stored.
The word in turn indicates what action should be taken when the word is executed. In the case of all words, the CFA points to a C function which is to be exe-cuted when the word is executed. For a primitive, there is no other action which will occur beyond the execution of the associated function. In a primitive the DOES>
field is always 0.

~ . - .: ., , ~ : . . .. . ..

Figure 3 illustrates the implementation of a typical thread. In this case, it represents the execution behav-ior of the word "u." whose behavior is commonly defined by the colon de~inition : u. <~ #s #> type space ;

Like all words in C4TH, it has an associated header and it begins with three fields:
1 'HEADER -- points to the associated header 2 DOES> -- if this word was created by a defining word using the CREATE -- DOES>
construct, this field points to the DOES> portion of the defining word.
Otherwise this field is 0.
3 'CODE -- points to an associated C
function which will be immediately executed to start the execution of this word. In the case of a primitive, this C function will be the only thing executed when this word is executed. In the case of a thread, this field points to a C function named xcolon.
These three fields are followed by the parameter field of the thread. This consists of a series of point-ers to words which are to be consecutively executed when the thread is executed. Data parameters serving as in-puts to these words may be intermixed with the pointers.This is not illustrated in Figure 3 but can be seen in Figure 4.
Figure 4 shows a more complicated arrangement of threads, such as would be produced by the compilation of the following two statements:

212~1~2 : u. <# #s #> type space ;
: test 7 + u. ;

The effect of the word test is to add seven to the value on the top of the parameter stack and print the re-sults. When the word test is executed, the interpreter pointer (IP) points to the beginning of the parameter field as shown in Figure 4.
The code for the inner interpreter is shown immedi-ately below the interpreter pointer. As it executes, itperforms a doubly indirect function call to the C func-tion xlit, advancing the interpreter pointer to the next position in the thread, leaving it pointing to the lit-eral value 7. The xlit function places the value pointed to by the interpreter pointer, 7, onto the parameter stack and advances the interpreter pointer, leaving it pointing to the reference to +. xlit then returns control to the inner interpreter.
The inner interpreter then performs a doubly indi-rect function call to the C function xplus, advancing theinterpreter pointer to the next position in the thread, pointing to the reference to "u.". xplus adds the top two values on the parameter stack and leaves the result on the parameter stack. It then returns control to the inner interpreter.
The inner interpreter then performs a doubly indi-rect function call to the C function xcolon, advancing the interpreter pointer to the next position in the thread, pointing to the reference to "; ". xcolon pushes the current value of IP onto the return stack, and then sets IP so it points to the beginning of the thread in `~ the word "u. " . It then returns control to the inner interpreter. In effect, xcolon has performed a transfer of control from the thread test to the thread "u. " in a ¦ 35 manner analogous to a subroutine call. At the comple-tion of execution of the thread "u. ", control can be re-turned to the thread test using the value saved on the return stack.

:~' The inner interpreter then consecutively executes the code for each of the words specified in the thread for "u.". At the conclusion of the thread for u. The inner interpreter will execute the code associated with the reference to ";" -- the C function xsemicolon. This function pops the top of the return stack, placing the return address back into IP. This is analogous to a re-turn from a subroutine call, and at the conclusion of this operation, xsemicolon returns control to the inner interpreter which will resume interpretation of the thread for test.
At this point the end of the thread test has been reached and xsemicolon is called once again, returning control to whatever routine had originally invoked test.
Created words come in two flavors:
1. Simple data words, and 2. more complicated doer words.
A simple data word provides storage for one or more items of data. When it is executed, it simply returns the address where the data can be found. An example is shown in Figure 5. The 'CODE field of a simple data word always points to a C routine called xvar and the DOES>
field is 0. When executed, xvar returns the address of the parameter field for the word which called it.
Simple data words are commonly brought into being using the word create which will create a word whose ¦ 'CODE field points to xvar. The user will then store data into the word using storage allocation words such as "," or allot. The example shown in figure 5, which con-tains the values of the first eight prime numbers, could be created using the following C4TH code:
create xlat_tbl 2 , 3 , 5 , 7 , 11 , 13 , 17 , 19 Such a word could be used together with another word to return the value of any of the first eight primes, 2122~82 given a number as an input. An example of such a word would be : Nth-prime ( ul -- u2 ) CELL * xlat_tbl + @ ;
In practice, one could view xlat_tbl as a simple array, and Nth-prime as a word which accesses the Nth ~ entry of that array.
j The more complex doer words also provide storage for data, but in addition they provide an associated access routine which determines what happens when the doer word is executed. In every doer word the 'CODE field points to the C function xxdoes and the 'DOES> field points to a thread which describes the access behavior for the word.
An example is shown in Figure 6. The arrangement I illustrated in Figure 6 would be created by the following code:

: array ( -- ) create does> ( ul -- u2 ) ~ 20 swap CELL * + @ ;
?1 array xlat_tbl2 2 , 3 , 5 , 7 , 11 , 13 , 17 , 19 , ~! test_it 4 xlat_tbl u. ;
, .
I This is similar to the previous example, in which we create a word called xlat_tbl2. However, this time the word xlat tbl2 is a doer word. Any time it is refer-.; _ ' enced, it will use the top value on the parameter stack ~ as an index into its contents and return the correspond-,! ing value. The word test_it is a simple test word illus-trating the behavior of xlat_tbl2.
When test_it is executed, it will place the value "4" onto the parameter stack and then execute xlat_tbl2.
When xlat_tbl2 is executed, the C function xxdoes takes control and does the following:
. .
1. It pushes the current value of IP onto the return stack.
~`
2. It loads IP with the address contained in the 'DOES> field of xlat_tbl2. In , .

effect it has transferred control to the access routine specified by the does> portion of the word array.
3. It pushes the parameter field address of xlat_tbl2 onto the parameter stack.
This will provide an input to the access routine, letting it know where the data can be found.
4. It then returns control to the inner ; 10 interpreter, which will then proceed to execute the thread given by the access routine in array.
The access routine uses the index value "4" (second item on parameter stack) together with the address of the data (first item on the stack) to compute the address of the fourth item of data and fetch its contents. At the end of the access routine, the primitive xsemicolon is executed, returning control to the thread in test_it which then prints the result -- 11. Note that the index r~20 value "4" actually accesses the fifth element of the array in xlat_tbl2; i.e., it uses 0-based indexing.
~l200L and FSML operate by creating words and data structures which appear to be ordinary words to the inner ~interpreter; i.e., it can interpret their behavior just `l25 like any other words.
Figure 7 illustrates the format of an important data structure created by 200L called a static named object (SNO). Such an object could be created by the 200L
syntax <classname> MAKE test A static named object has the following properties:
, 1. It has a header in the dictionary and ! 35 an associated symbolic name; i.e., it , , -21-:, .

., .,, .. , ... . . . ; .. ... . . . . .. .. . . .

has a name by which it can be referenced.
2. It is actually implemented as two related words -- wordA and wordB.
wordA is executed any time the word is being referenced by its symbolic name ¦ (note that the CFA field of the header points to wordA).
3. When an SN0 is referenced by its s~mbolic name, wordA is executed and generates a reference to the second word, wordB. It also leaves the address of the descriptor for the SN0 on top of the parameter stack. In generates the reference to wordB in one of two different fashions, depend-i ing on whether the C4TH system is in 3 interpret or compile mode (identified `? by the contents of the user variable state):

~t a) If state is 0, indicating that C4TH is in interpret mode, wordA
will leave the address of the ~i parameter field of wordB as the second item on the parameter stack. It will leave the address of the descriptor on top of the ~i parameter stack.
~' b) If state is non-zero, indicating J? 30 that C4TH is in compile mode, 't wordA will compile the address of the code field of wordB into the dictionary. It will also leave ' the address of the descriptor on ~? 35 top of the parameter stack. When the thread which is being ~1 -22-ii ? ` . ' . i`: ~ ' compiled executes, it will in - turn execute wordB which will at that time leave the address of its parameter field on top of the l 5 parameter stack.
's':
~, 4. When a reference to wordB is executed, it will leave the address of its parame-ter field on the parameter stack, indi-cating where the data can be found.
Any time a reference is made to a SN0 using its symbolic name, the address of its descriptor is left on top of the parameter stack. This address is used by the following method name to determine what class the SN0 belongs to. Knowing the class to which the object be-longs and the name of the method which is to be applied to that object, it is then possible to generate a refer-ence to the thread for the ap~ropriate method to be used to operate on the object.

The implementation of 200L is presented by describ-.s~
;~ ing, step by step, how the 200L system handles a typical example of 200L code. The example is as follows:
,:~
01 method: set_seed 02 method: raw_random 03 method: rand 04 class: random 05 private:
30 06 short: +seedl 07 short: +seed2 .,.~
08 public:
09 m: set_seed ( u -- ) oa +seedl !!
35 10 0 oa +seed2 !! ;m 11 m: raw_random ( -- u ) oa +seedl @@ 307 *
;~1 12 23 + dup oa +seedl !!

,~

.... . . . . . . ~ . . .. . . . ... ... .. .. ... . . ... . . .. ... . ...... ... . ...

--` 2~22~ 8~
13oa +seed2 @@ 521 * 29 +
14dup oa +seed2 !! + ;m ) 15m: rand ( ul -- u2 ) oa raw_random ; 16 swap mod ;m 17 ;class i 18 random MAKE my_random 19 478 my_random set_seed 20 6 my_random rand Note that each line is preceded by a line number.
These line numbers would not normally be present in 200L
l~ code, but are placed in the example to facilitate refer-3 encing individual lines in the description which follows.
s 15 Line 01: the word method: is a keyword defined in 200L. It takes the following word provided by the user, in this case the word set_seed, and defines it as the name of a method. It does this by defining the word set_seed as a doer word. method: allocates a unique index number which it assigns'to set_seed. This index I number is subsequently used to cross-reference the sym-bolic name set_seed with the actual method code defined in the class. The data structure built by method: is illustrated in Figure 8.
Index values are assigned starting with the value 4.
Each new index value is four greater than the preceding `l value; i.e., the two least significant bits are zero.
' These bit positions will be modified depending on whether ;'l! the method is public or private.
method: also provides the access routine used by set_seed any time set_seed is referenced. This access routine expects that, at the time of reference, the top value on the parameter stack will point to a class ~ descriptor. The access routine takes the following j 35 actions:
1. It performs a sanity check to verify that the top item on the parameter stack was a pointer to a class descriptor .

.~, ~ `
, .

, - . . .. . - .-, .. .

212~82 2. It then searches through the methods-list of that class descriptor, looking for a methods_node whose index field matches the index value assigned to this method. If it does not find such , a methods_node, then this method is not valid for that class and an error message will be output.
3. Assuming that a methods_node can be ! lo found, then the access routine will determine the address of the code for .;
the method and will either execute that code immediately or compile it into the dictionary, as appropriate.
Lines 02 and 03: like Line 01, these lines define two additional method names: raw_random and rand. The corresponding data structures are illustrated in Figure ,,, g Line 04: the word class: is a keyword defined in 200L. It starts the definition of a new class by doing ~l~ the following:
. It creates and initializes a descriptor for the class random.
. It loads the variable curr-class with ~ 25 the address of the descriptor for `~ random.
. It leaves a value of 0 on the top of the parameter stack. As each element ~, making up the structure of the class ~ 30 random is defined, this value will be .~ incremented by the number of bytes of space required by that element. At any given time this value indicates the offset from the beginning of the object to the position occupied by the ~ next element to be defined. After all .~ -25-.''jl ~s ;~ 212~82 ., elements have been defined, this value ~, will indicate the size of an object of ~: this class.
, The initial data structure for the descriptor is illustrated in Figure 10. The contents of this ~, descriptor will be modified as the class is further defined.
The descriptor consists of four elements:
:.
~1 1. A descriptor list which will eventu-:i 10 ally comprise a linked list of de-scriptor nodes, each of which will ~' describe a portion of the structure of an object belonging to this class. At the time the descriptor is created by ~, 15 the word class:, the descriptor list - is empty, indicated by the 'DN_NODE
field being null (O).
. ~
~, i 2. A methods list which will eventually ::.
~I consist of a list of method_nodes, each of which identifies one or more methods which are defined for this class. At the time the descriptor is - created by the word class:, the method list consists of a single item -- a method_node which points to the de-; scriptor for CLASSO. This method node indicates that all of the methods de-fined for CLASSO are also defined for the new class random.
` 30 3. A size field which indicates the natu-ral size in bytes occupied by an ob-ject which belongs to this class. At the time the descriptor is created by the word class:, the size is not known and this field is initialized with a value of 0.

, -26-,, - 2122 ~ 82 4. A subclass list which links together ; all the subclasses which may be de-fined within this class. At the time the descriptor is created by the word class:, the subclasses are not yet de-fined and the subclass list is empty, indicated by the 'subclass field being null (0).
3! Line 05: private: indicates that those methods which are subsequently defined should be treated as local to this class and not accessible to words which are defined ~ outside the scope of this class definition. The word a' private: is very simple -- it clears a flag in the vari-~l able public-flag. Those keywords which define methods always examine this flag at the time they define a method s and make it public or private accordingly.
; Line 06: the word short: is a keyword defined in 200L. It takes the following word provided by the user, ~ in this case the word +seedl, and defines it as the name r~ 20 of a method. It also indicates that the first element of any object belonging to the class random should be treated as a short (2-bytes long), signed integer. As the word short: executes, it performs the following actions:
. It defines a new method, much as method: does, giving it the name +seedl.
. It creates a descriptor node indicat-ing that the first element within an ~ 30 object of the class random is a short, i's~ signed integer.
. It attaches this descriptor node to the end of the descriptor list.
It creates a method node, indicating that the method +seedl is a valid method for the class random.

i~
. .

. ~ .. = . . .. ... ... . . .. ~ . .. . ... . . ... . . ... .. ~ . . .. .. .. .. . ... . . . .. . ... .. .. . .

21221~
' - . It attaches this method node to the !~! beginning of the methods list of the descriptor for the class random.
It creates a word sharing the symbolic name +seedl and having the execution ;1 time behavior necessary to access this element in any object belonging to class random.
. It increments the offset value found on the top of the parameter stack by two, indicating that the size of an object belonging to class random is known to be at least two bytes long -~ and that the next element to be de-fined will be at an offset of two from the beginning of the object.
.
The results of executing short: +seedl are illus-~ trated in Figure 11. Those portions of the figure which :j are shaded indicate data structures created and initial-ized by the word short:. The format of the method_name . (lines 1-4) is virtually the same as that created by method: and its 'DOES> field points to an access routine that is essentially identical to that generated by method:. Like any method name, it has a unique index value.
A method_node created by short: has three fields:
1. A link field used to link method_nodes together into a linked list -- the methods-list.
2. An index field which stores the same ~-l index value that is associated with i,h~ the method name; i.e., there is a one-to-one association between the con-` tents of this field and the method `i~ 35 name. When this field is initialized, '~ the least significant bit is set to .

~, .

:
`?i 212~182 "1" if the public-flag indicates that - this method should be treated as pub-;i lic for this class. Otherwise this I bit is cleared to zero.
3. A 'method field which stores the 7 address of the word which specifies ~.~
the behavior of this method for this class.
~j Given the symbolic name of a method, it is easy to determine the associated index value. It is then possi-`~ ble to search the methods_list of any given class t~' descriptor to find a method_ node having a corresponding index value. If no such method_node can be found, then that method is not defined for that class. Assuming it is found, it is then possible to go from the method_node to the address of the code which is to be executed when that method is applied to an object belonging to the class.
;~ A descriptor_ node has three fields:
,~
1. A link field used to link descriptor_nodes together into a linked list -- the descriptor-list.
2 A 'descr field which points to a de-scriptor providing infor~ation about the element.
~,$
3. A copies field which indicates whether the element is actually an array of items described by the 'descr field, or whether it is in fact a single item of the type specified by the 'descr field. A value of -1 indicates that this is a single item, not an array.
short: will always create a descriptor node whose 'descr field points to a descriptor for the class SHORT.
This descriptor is provided as part of 200L. This descriptor indicates that the size of an object (or ,:t `~ -29-!
"I
., , 2~22182 element) of type SHORT is 2 bytes. Its descriptGr_ list is empty. This is characteristic of a data type which does not contain any substructure. Its methods_list ; contains methods_nodes for a number of methods which are defined by OOL as being applicable to an object (element) or type SHORT. This includes methods such as PRINT, DUMP, A DDR, SIZE, !!, MAKE, etc.
The method created by short: is relatively simple and is structured like a doer word. Its 'HEADER field points back to the header for the symoolic name +seedl.
Its 'DOES> field points to an access routine which adds the offset of the element to the top value on the parame-ter stack which contains the base address of the object.
The effect of this is to generate the address of the ele-ment +SEEDl. Like all create-does> words, the 'CODE
field points to the C function xxdoes(). The parameter field contains a single value -- the offset of the ele-ment. Since +seedl is at the first element in the ob-ject, the offset value is 0.
Line 07: the word short: is encountered once again.
It takes the following word, +seed2, and handles it al-most identically to +seedl. A different, unique index value is assigned and the offset value is now 2 instead of 0. The value on top of the parameter stack is incre-mented by 2 ~the size of a short element), leaving a result of 4.
Line 08: public: indicates that those methods which are subsequently defined should be treated as publicly .; known; i.e., not restricted to use only by methods de-fined within this class. public: is the opposite of private: and like private: it is easily implemented -- it sets a flag in the variable public-flag.
Line 09: m: starts the definition of the method ~ set_seed by performing the following actions:
cll 35 1. It uses the C4TH dictionary search routines to verify that there is a method-name defined for set_seed. If it cannot find such a method-name, it returns an error message.

`;
.

,.

':
`-- 2122182 .. .
2. Assuming the method-name is found, it obtains the index number assigned to that method-name.
3. It constructs a method-node, using ;~ 5 that index value, and links the method-node into the methods-list.
.~
4. It constructs the first part of a word i definition -- the 'HEADER, 'DOES>, and 'CODE fields.
5. It initializes 'HEADER to point to the header for the method-name; ' DOES> to , 0; and ' CODE points to the C function ~, xcolon(). This word will be a thread.
;:;
~`~ 6. It compiles the CFA for set-oa as the first entry in the thread.
7. It then puts C4TH into compile mode, allowing C4TH to compile the rest of the method.
!~ :
~ The word set-oa handles a simply utility function ~-1 required at the beginning of the execution of any method -- it saves the current value of the constant oa onto the return stack and places the top value from the parameter stack into the constant oa. By convention, this value will be the base address of the object that the method is acting on.
When the word m: completes execution, that data structures are as shown in Figure 12. Note that descriptor-nodes are inserted into the descriptor list at .;, the tail of the list. This ensures that a traversal of the descriptor list from the beginning to the end corre-~ sponds to a traversal of the elements in the object from ','3i base address to the end of the object.
Methods-nodes are inserted into the methods-list at ^~1 the front of the list. This allows a method to be ~ . .
~:' ;~', ~ 2~22~ 82 defined multiple times within a class but only the most recent, public version of the method will be recognized.
Line 10: ;m completes the definition of a method.
It compiles the word mexi t into the dictionary and then invokes the word ";". The word mexit performs the in-, verse function of set-oa -- it pops the top value from the return stack and places it into the constant oa, restoring the value that oa had prior to the start of execution of the method. The result of compiling lines 9 and 10 is shown in Figure 13.
Lines 11 to 16: define two more methods --raw_random and rand. The compilation of these lines is -~ no different than that of lines 9 and 10.
Line 17: ;class completes the definition of the class random. It does so by performing the following ' actions:
:, , 1. It takes the top value from the i parameter stack and places it into the 5! size field of the class descriptor.
In the case of the class random, this value wlll be 4.
~' .
2. It then invokes the conceal routines to mark the pri va te methods as inva-lid. The conceal routines traverse i~ 2~ the methods-list, searching for those ,, method-nodes whose index field has the ~; least significant bit clear, indicat-ing that they are private, not public.
, It then sets bit 1 of the index field - 30 for each of these method-nodes. When . bit 1 is set, the search routines which search the methods-list for a given index value will fail to find a match on these methods-nodes; i . e., ` 35 they will no longer be detected as valid for this class.
This method of hiding methods-nodes which are private was chosen because it is easily reversible for ~ .
.,, .,;. : : ~ . , , -- - .
~ : , :

2122~ ~2 debugging or for exceptional cases where two classes need to share information which is otherwise private.
; Line 18: random MAKE my_random will create an in-stance of the class random and give it the symbolic name ; 5 my_random. The following actions take place as these words are executed:
` 1. The word random is the name of a class ` descriptor which is itself an object belonging to CLASS0:. Its behavior is the same as any other object name: It places the address of its contents ,;~ (the descriptor for the class random) ; onto the parameter stack. It then places the address of the descriptor of the class to which it belongs, , .
CLASSO:, on top of the parameter : stack.
, 2. The word MAKE is the name of a method.
`;~ Like any other method-name, it expects i~! 20 to find the address of a class de-scriptor on top of the parameter stack. It then searches the methods-list for this class, CLASS0:, to see if there is a method-node whose index value matches that of the method MAKE.
Such a method-node exists and points to the code which will construct an object belonging to the class random.
This code will now be executed.
3. The MAKE method expects to find the address of a descriptor on top of the parameter stack. This was provided by the word random. The code for MAKE
examines the size field of the descriptor and creates a static, named object having the specified amount of storage. The word which follows MAKE

'`
. .
:.

:
- 212i~2 will be used as the symbolic name for the object ~- my_random. The contents of my_random will be undefined.
` Line 19: 478 my_random set seed will initialize the contents of my_random. The following actions take place as this code is executed:
1. 478 leaves the literal value 478 on ` top of the parameter stack.
2. my_random is the name of an object.
~' 10 It places the address of its data contents onto the parameter stack. It then places the address of its class descriptor on top of the parameter stack.
3. the word set_seed is a method. Like any other method-name, it expects to find the address of a class descriptor on top of the parameter stack. It ~ then searches the methods-list for i! 20 this class, random, to see if there is a method-node whose index value ; .
matches that of the method set_seed.
Such a method-node exists and points to the thread which was defined for set_seed. This code will now be executed.
~ 4. As the code for set_seed executes, it `~ first finds the address of the object, ~ .
`~ my_random, on top of the parameter stack. The word set-oa saves the value of oa and places the object address into oa so that future refer- -` ences to oa will return the object address. set_seed then performs the ~ 35 initialization, placing the value 478 ; into the +seedl element of my_random, and 0 into the +seed2 element. At the : -34-.' ,.
end of set_seed, the word mexi t re-stores the original contents of oa.
Line 20: 6 my_random rand operates in a manner perfectly analogous to that of line 19.
FSML
~ The implementation of FSML is presented by .3 describing, step by step, how the FSML system handles a l typical example of FSML code. The example is as follows:
i ~ 10 :-, 01 input inO
-, 02 input inl ':
..
I~ 03 input tml ,j15 04 tml 20 create-timer timerl 05 user tl ! :
06 machine ml 07 ." activating instance of ml" cr 08 states ;~ 09 sO
sl 11 end-states ^~ 25 ~' 12 state sO
:~ 13 inO sO { ." received inO while in sO" }
:~ 14 inl sl { ." received inl while in sO"
~, 15 timerl start-timer tl ! }
30 16 or-else sO { ." unexpected input while in sO" }
.
17 state sl .~, 18 inO sl { ." received inO while in sl" }
`` 19 inl sO { ." received inl while in sl"
; 35 20 tl @ stop-timer }
.. 21 tml sO { ." timerl expired " }
22 or-else sl { ." unexpected input while in sl" }
.i .~ -35-212~182 ,~
23 start-state sO

24 m-schedule ml alias mtm ( mtm == my test machine ) select mtm ~' 5 26 inl >
!,~ 27 73 >>>
,., Line 01: input is a keyword defined in FSML. It takes the following word and makes it the symbolic name for referencing an input to a machine. It does the ', following:
1 It generates a unique token value that will be used to uniquely identify this input when received by a machine.
~, .
2 It creates a constant havlng the symbolic name (in this case inO ) and initialized to the value of the unique token.
3 It links the new word into a linked ~¦ 20 list of all inputs.
4 It compiles the value OCCE8H as the ~: next entry in the dictionary.
~l The results of this are shown in Figure 14. The ,.,2 value OCCE8H is compiled to provide a convenient means of . 25 checking whether a particular entry in the dictionary is an FSML input -- if the third entry in its parameter ,value is OCCE8H, it is assumed to be an FSML input. -Line 02: defines another logical input name -- inl.
The actions taken are virtually the same as those indi-cated for Line 01. The results are shown in Figure 15.
Line 03: defines another logical input name -- tml.
The actions taken are virtually the same as those indi-cated for Lines 01 and 02.
Line 04: tml 20 create-timer timerl has the effect of defining a type of timer whose symbolic name is timerl. It does this in the following steps:
/, . -36-,i;

.
~12~182 ,............ .~,.
1 tml is the name of an input, and like all inputs acts like a constant. When it is executed it returns its value on ; the parameter stack. In this case the value 3.
h, ~! 2 20 is a literal value which leaves the ~ value 20 on top of the parameter '! stack.

3 create-timer does most of the work.
It creates a timer structure whose symbolic name is timerl. Execution of a reference to timerl will return the address of the timer structure.
:j The results of this code are shown in Figure 16.
i:~ 15 ~.ine 05: user tl is just ordinary C4TH code, re-serving a user variable which will subsequently be used to store the timer token returned by starting the timer.
Line 06: machine ml begins the definition of a type ~ of machine which will be named ml. The work is done by .-i 20 the word machine which does the following:
~ 1 It creates a simple data word whose -ri symbolic name is ml. It then proceeds to initialize the contents of this , word, making it something of a hybrid , 25 between an ordinary data word and a ` thread.
i~l 2 It initializes the variable curr-mach ,; to point to the parameter field of the ~`~ word ml.
!- .
~.
3 It compiles the literal value OFEE5H
'`! as the first entry in this word. This j value is used for sanity checking --;` verifying whether a word is a valid machine type.
i~ l ~ -37-~?

212~82 ., 4 It begins compiling a thread; starting with a section of code which will initialize the starting state of the machine when it is executed. Because the starting state is not known at this time, the variable Ist is set up pointing to the fragment of code which will need to be fixed up later to identify the proper starting state.
The results of this are illustrated in Figure 17.
, 5 It then switches C4TH into compiling 3 mode, allowing the normal C4TH com-pilation process to complete the com-pilation of the thread.
Line 07: ." activating instance of ml" cr specifies a fragment of code which is to be executed any time a machine of type ml is created and starts running.
Normally this would be problem specific initialization code. In this case it is a simple message indicating ~ that the machine has been created and started executing.
^j Lineq 08 to 10: states terminates the definition of the initialization code and begins a block of code which will identify the symbolic names of all of the states for the machine ml . It performs the following actions:
1 It compiles a reference to (run-mach) ; at the end of the initialization code.
(run-mach) is the actual routine which , handles input processing for a machine; i.e., when initialization ~ processing is complete, (run-mach) '~ gets control and starts processing `~ inputs as they become available.
~l;
2 It executes the word ; allowing it to finish the thread.

' ;~ -38-`' ~ : ' . : :

/

-~-` 2122~2 3 It then loops through the next series of words, making each of them the symbolic name for a state. The looping process terminates when it :1 encounters the keyword end-states.
The result of this process is shown in Figure 18.
The data structures for each of the state names have the following properties:
. The state names are simple data words, so their execution time behavior is to return the address of their data 1 contents.
. Z
,~! The first field is initialized to 0.
~ While the behavior of the state is .3 15 being defined, this field will serve ~ as the head of a linked list of all j., the threads of code which specify the actions for each of the inputs which are defined for this state.
. The second field is initialized to -1.
` This is a flag indicating that the .~l state name has been defined but has not yet been used in a statement such as state sO. When the state behavior is specified, this field will point to ~ the State Input Table associated with ; that definition.
. The third field is a link field. All state names for a particular machine are linked together in a linked list.
st-lnk is a variable which points to the first entry in this linked list.
. The fourth field is the constant value O9ADDH which is used for sanity check-ing to determine whether a particular :~ .
~ 39_ is, :
, .

212~182 word corresponds to a valid state name.
D The fifth field is a pointer to the i data structure generated by the word 3 5 machine. In this fashion, given a state name, it is possible to deter-~; mine what machine it is associated with.
Line ll: end-states has no behavior of its own. It simply serves as a terminal indicator for states, indi-~? cating the end of the list of states.
~ Line 12: state sO begins the definition of the Ji behavior exhibited by the machine while it is in state sO. All of the work is done by the word state which takes the following actions:
` l It checks sO to verify that it is a valid state name, defined by states ... end-states.
2 It verifies the fact that this is the i 20 first occurrence of state sO; i.e., the behavior of sO has not been previously defined.
3 It begins building the State Input Table entries required to define this states behavior.
~, ,, a) It places an entry in the SIT
that points back to the body of the state name.
b) It places a pointer to the rou-tine process-input into the SIT, indicating that this routine should be used to evaluate the contents of the subsequent ` entries in the SIT.
.. . .

, 21221~2 4 It stores in the second field of the state name definition of sO a refer-ence to the relative position in the SIT of the link to process-input.
f 5 This information will be needed at a Al later time to patch up address refer-'f ences which cannot be initially f resolved.
The results of this processing are illustrated in Figure 19.
' Line 13: inO sO { ." received inO wnile in sO" }
f~ specifies the behavior of state sO when input inO is ~ received. Most of the work is done by the word {O The 3 following actions occur:
' 15 1 The word inO is executed and leaves its value on the stack, a "1".
' 2 The word sO is executed and leaves the j address of its associated data on the i stack.
' 20 3 The word { is executed and performs the following actions:
~,f a) It verifies that the input value ;f left on the stack is valid and i i`f~ produces an error indication if C! 25 it is not.
i~l ~ b) Assuming the input value is 'qj valid, it is entered into the SIT.
c) The current value of here is `sf 30 entered into the SIT. This provides a pointer to the loca-, tion in the dictionary where the .` thread which defines the action ;i associated with the input will be ~ 35 located.
~, .
` -41-f:;

i ~
212~1~2 ` d) The preceding three steps will be repeated until there are no more input values remaining on the parameter stack. In the case of this example there is only a single input value, but the syntax of FSML allows for multiple values.
~;, e) It checks the address left by sO
;.
,- 10 to verify that it is indeed the : -, ~ address of a valid state name.
~, f) It begins to construct the thread which will be executed any time a i: .
;~ machine of type ml receives an ~r' 15 input value of inl while in state ` sO. It links this thread into a , linked list of threads associated :
~- with the state name sO. This is done via the first element in the data for the state name. Eventu-ally this link field in the thread will be replaced with the identity of the next state sO.
g) It then concludes by putting the C4TH system into compile mode, allowing the regular C4TH com-pilation process to finish com-piling the thread. At this point in time, the appropriate data ;~ 30 structures are as illustrated in Figure 20.
4 The C4TH compiler processes the code fragment ." received inO while in sO"
and compiles it into the thread.
~ I
~,'1 .
~ -42-,'~

5 The C4TH compiler encounters the word } which ls immediate and executes it.
6 The word } terminates the compilation of the thread. Depending on a user option, it may compile a reference to ~stk-chk) at the end of the thread.
! This word performs a runtime check for spurious data left on the stack. }
then calls ; to terminate the definition.
The results of all this processing are shown in Figure 21.
Lines 14 and 15: inl sl { ." received inl while in sO" timerl start-timer tl ~ } is processed in virtually the same fashion as the preceding line. The result of this processing is illustrated in Figure 22.
Line 16: or-else sO { ." unexpected input while in sO" } is processed in the same manner as the preceding lines. Note that as far as FSML is concerned, or-else is just another input whose value happens to be -1. FSML
~3 does enforce a syntax rule that if an or-else input ; occurs, it must be the last input within the state definition.
Line~ 17 to 22: these lines are processed in the same manner as lines 12 to 16.
Line 23: start-state sO concludes the definition of the machine ml. start-state has a lot of work to do as follows:
1 It verifies that the word which follows, sO, is the name of a state which has been defined for machine ml.
If it is not it ~enerates an error message.
2 Assuming it is a valid state, it patches the reference in the initiali-zation code to refer to the portion of h, the State Input Table which is associ-ated with this state.
3 It then copies the State Input Table into the dlctionary.
4 It then traverses the list of all state names associated with the machine ml, verifying that all states are reachable and resolving all pointers to the State Input Table, replacing them with the actual addresses occupied by the SIT in the dictionary. It is at this point that the next state field of all of the action threads is updated to indicate the next state value.
'3 5 It then reinitializes various compila-tion state variables to allow the ~3 definition of any additional machines.
Line 24: m-schedule ml alias mtm creates an instance of the machine ml and creates an alias name for the in-stance, making it convenient to refer to the machine in-stance by the symbolic name mtm. The following actions take place:
1 m-schedule creates a task using the ~, 25 facilities of FMTOS. It initializes this task such that when the task begins to execute, it will start interpreting the thread of initializa-tion code associated with the machine ml.
2 m-schedule also creates a pipe for handling input messages and initial-izes the new task's user variable my-pipe to point to that pipe.
. . .

. .
;! ?~

;

212~82 - 3 m-schedule then initializes the re-covery procedure for the new task to point to mrcvy-rout, the default re-covery routine for an instance of a finite state machine.
4 m-schedule completes its activity by placing the new task in the scheduling queue and returning a token pointing to the task control block.
5 alias takes the token provided by m-schedule and creates a constant having that token as its value and the ~, symbolic name mtm.
1i As soon as the machine mtm gets control from the task scheduler it will begin executing its initialization code. It will print out the message activating instance 3 of ml followed by a carriage return. As it reaches the end of the initialization code, it will begin executing the routine (run-mach) which will essentially loop for-ever, waiting for inputs and processing them as they :' arrive. (run-mach) will immediately attempt to remove an input message from the input pipe. In all likelihood, none will be available and the task will block, waiting for an input.
Line 25: select mtm makes the machine specified by ~;~, mtm the "current machine". This is a convenience pro-vided for debugging, making it easy to interactively send inputs to the selected machine.
~, Line 26: inl >~> sends the input inl to the cur-rently selected machine. Most of the work is done by >~>. The following activity occurs:
1 inl leaves its value, 2, on top of the stack.
2 >>> takes the top value from the parameter stack and makes an input message from this input value ~`

21~182 3 > then sends the input message to - the selected machine, mtm . The format of the input message is illus-trated in Figure 23. Sending the message will unblock mtm, placing it back into the scheduling queue.
The message has five fields:
. FLINK and BLINK and linked list point-ers used to link the message into the input pipe of the receiving machine.
'TCB gives the task identity of the task which sent the input. This is provided primarily for debugging.
. IN contains the value of the actual input.
. 'PROCESS contains the value that the user variable 'process had at the time the input message was sent.
As soon as the machine mtm gets control from the task scheduler, (run-mach) resumes execution and does the following:
1 It saves the current state in a vari-able mstate.
2 It removes the value of 'process from ~ 25 the input message and places it into ;I the user variable 'process.
3 It removes the input value from the input message and places it into the user variable in-save.
4 It checks to see whether the input message originated from a timer op-eration. If so, the buffer is not attached to the input pipe and should be released using an mput operation.

~ .
' 212~82 .
Otherwise, the empty input message is returned to the pipe.
5 It then transfers control to input processing routine specified for the ~ 5 current state, commonly process-input.
; 6 process-input will search the State Input Table associated with the cur-rent state, looking for an input value which matches the received input.
i 10 Once this is found, it will transfer ; control to the thread indicated by the SIT and update the current state to indicated next state. This thread will perform the actions specified for :~j ; 15 the received input. When the thread ;~ is completed, it will return control to (run-mach) which will once again wait upon another input.
Line 27: 73 >>> sends the input value 73 to the .~ 20 currently selected machine. The processing is virtually the same as that for line 26, however, 73 will not be a recognized input value, causing activation of an or-else vl action.
HOW TO D~SIGN A MODEL
With an understanding of the FMTOS; 200L and FSML
extensions to C4th, the user is ready to create a model which simulates a target real-word system being investigated.
First Level -- Identify and Classify Main System Objects a. Describe the system as a collection of objects which relate as directly as possible to the target system com-.~ ponents. Identify the objects as "controlling objects" and "controlled objects". Controlling objects can ~ receive input stimuli from and pos-'t~ sibly send OUtplltS to the environment i! -47-,, "
:, .
,..

212~1~2 (which can be a user at a terminal, data link to another system, another controlling object, etc.) There must be at least one controlling object.
b. Inputs and outputs must be defined as event messages which, at a mlnimum, must correspond to event tokens (an event token is unique value specifying a specific event). A message may also contain other information elements whose forms may be later specified in detail by 200L (non-controlling) ,j object class definitions.
~j c. Controlling objects should be speci-fied as Finite State Machines, using FSML. When a Finite State Machine receives an input event, it generally executes a state transition and ma-~, nipulates other non- controlling objects which represent the elements of the system that are being ,0 ~! controlled.
~, ij d. Controlled objects do not need to be ;î implemented until the controlling processes of the controlling objects are operational and well understood.
This implies the controlling can , accept all input events and make all 3 state transitions properly.
To define new controlled objects, the user will usually need to create new 200L object classes corre-sponding to the objects that represent the system being modeled. New classes comprise a definition of instance data for the class and a set of methods that (usually) operate upon that data. The instance data is defined in terms of primitive data objects pre-defined in 200L, and as instances of other pre-defined 200L object classes.

`':

~ 22~ g2 Define new methods as required:
a. Methods defined generally in the Forth language primitives within the context of 200L class definition.
b. Methods which invoke the inherited methods of the objects that comprise the new class 7 S instance data.
c. Methods which invoke other methods of the new class that were defined earlier in the class definition.
Second Level -- Refinement of Finite State Machine (FSM) Controlling Objects Designing an FSM requires the following steps:
; a. Determine all the states.
i b. Identify all inputs, and which inputs are valid in each state.
c. Define which state the machine should transition to for each valid input.
:.
d. State what action should be performed for each input-transition pair. The "action routine" during initial design should be nothing more than a printed message to the user about the action to be taken.
Third Level -- CoIrununicating FSMs '. Each FSM definition defines a "machine type". When ,i the system executes, One or more instances of each ma-chine type must be created as an synchronously executing l task. FSML provides several communication mechanism , 30 alternatives for both "connection-oriented" and "connec-; tionless" communication linkages. Establish the most appropriate type according to the system being modeled and implement these mechanisms.

212~82 Fourth Level -- Expand Detail The complete system operation consists of communi-cating FSM processes. In the VoiceMailbox example, inter-FSM communication takes place between coexisting VoiceMailbox FSMs sending and receiving messages with each other. With each iteration of development of the model, the "controlled object" classes are implemented and the "action routines" are expanded to execute the methods of these objects. In the end, the model replaces the text display of desired action routing function by the actual execution of those actions upon the controlled objects of the system.
Basic Call Model Example ~ By way of an example, the present invention was used ;` 15 to model the Intelligent Network ~IN) as characterized by a Basis Call Model comprising a set of call state, called Points-In-Call (PICS), to define Originating and Termi-~ nating Basic Call models in conjunction with a model of ,tl the switch conductivity state defined in terms of a set of Connection View (CV) objects. With the Basic Call :~! Model (BCM) as simulated by the present invention, a generic switching systems is simulated in terms of finite state machine states and CV objects. Message communica-; tion between this simulated switching system and Service ~' 25 Logic Execution Environments (SLEEs) is modeled according to various protocol alternatives.
` The IN concept is intended to make the public tele-; communication network more flexible and responsive to the ~- changing needs of the network users. This is to be achieved by modifying existing central office switching ~` systems, and designing new switches, so that their call ` processing logic can be controlled or influenced by other ~` network elements (external computers programmed by tele-phone operating company personnel). The motivation for ~, 35 this is the long lead time required by switch vendors to . provide new services and features in the switches' em-bedded generic software packages and the amount of time needed to deploy the new services and features to all switches within a network.

''' 2~22~ ~
Prior to IN, it has been impractical to support large-scale local customization of central office switch-based features, to accommodate unique requirements of specific customers, and to introduce interfaces to other external computerized services. The IN concept makes these arrangements more feasible. Referring to FIG. 25, The IN strategy is to de~ine a small set of standardized points of control, called Detection Points (DPs), within new and existing central office switch software. At these points the switch will suspend normal processing logic and send messages to Service Logic Programs (SLPs) within other computers, called Service Logic Execution Environments (SLEEs), external to the switch. The SLP
then responds to the switch query with a response message i 15 that indicates which of several actions the switch should ; take as the next step in processing the call. Through a sequence of such interactions, an SLP can control a central office switch to effect service scenarios not provided directly by the switch software. The IN concept brings with it a variety of concerns including: stability `; of existing network elements, development costs, complex-;~ ity management, inter-vendor compatibility, OAM~P issues, future evolution paths, and others.
~ In creating the Basic Call Model Rapid Prototype ,~ 25 (BCMRP), two major FSM classes were defined; one for the Bellcore Originating Basic Call Model (FSM.O-BCM), and one for the Terminating Basic Call Model (FSM.T-BCM). See FIG 24. The BCM PICs are represented as states in FSML.
A typical, simple two-party telephone call requires an instance of an O-BCM and an instance of a T-BCM. More complex telephone calls may involve many more separate O-BCM and T-BCM instances which are interconnected and able to communicate by messages.
Although FSML syntax allows any arrangement of Forth code to be provided to specify the actions to be per-formed when a particular input occurs in a particular state, the BCMRP is implemented by combining all actions into special action words so that for every state-input pair, the action to be taken is defined by a single .. ! :

2~2~182 action word. This improves the clarity of the FSML code, emphasizing the table-like structure for states, inputs, next-states, and actions. Table 1 shows an excerpt of actual FSML code for the O.Actv (Originating BCM ACTIVE
' 5 PIC) submachine.
; In the BCMRP, the main control logic is implemented i as a set of communicating FSMs, implemented in FSML. The ~3 action words invoked by the FSMs perform their work by ~, applying the Method operations to the objects which de~
fine the fabric of the system. The BCMRP represents all CV elements (Call Segments, Legs, Call Segment Associa-tions, etc.), all messages and parameters as 200L ob-jects. The BCMRP represents elements of an actual proto-type's database as a set of 200L objects. For example, a line accessed via jack C38 on the prototype can be refer-enced by object name C38 in the BCMRP. Since C38 is an instance of a telephone line object class, it can respond to methods such as ORIGINATING, DIALING, ANSWER, HANGUP, ~ MAKE-BUSY, and so forth, in addition to primitive 200L
i 20 methods such as DUMP and PRINT.
i To initiate a new telephone call from line C38, one `-, could input:
::! C38 ORIGINATING
The BCMRP would create a new Originating BCM in-stance and prompt the user for the valid next inputs for the AUTHORIZING_ORIG_ATTEMPT PIC. If the Originated de-tection point is not activated for that particular line in the switch's database, the BCMRP would automatically ~-~ Continue and enter the COLLECTING_INFO PIC at which time the user could input:

and the BCMRP would prompt the user for the valid next ' inputs for the AUTHORIZING ORIG ATTEMPT PIC and the BCMRP
. 1 _ _ would advance the O-BCM to the INFORMATION_COLLECTED PIC.
Every switch event is analyzed for Detection Point criteria, and if the criteria are satisfied, a SLEE mes-~ sage is created. The message is displayed in user-`~ readable form on the terminal, and the user is then ~ prompted with a list of all valid SLEE responses. At .

..;

~ 2122~82 this time, the user can select which SLEE response is to be received, and a SLEE message is constructed. A11 -~ valid SLEE response messages are derived from the current FSM state (PIC) whose specifications are encoded in FSML
5 for the specific call model implemented. Once a particu-lar message is selected, the user is prompted for all parameter values and optional parameters. Depending upon the user's choices, the BCMRP will simulate various switch actions in terms of the abstract switching machine ~ 10 defined by the BCM PICs and conductivity states repre G sented by the CV objects. These are displayed after each ~-l response, and the user is again prompted for all valid next events.
;; Ordinarily, the BCMRP attempts to simulate most 15 switch actions automatically, but the user can override almost any switch action with whatever actions are valid within the BCM and message protocol specifications.
The BCMP interactive mode is usually used to create scripts which can then be saved as text files and run 20 through the BCMRP in batch mode. This makes it easy to build a large library of call scenarios by deriving new ~'l call variatlons from previous call scripts.
An optional output mode causes the BCMRP to create a Feature Test Plan (FTP) output file, where the human . 25 actions, such as call origination, are listed along with the resulting switch-to-SLEE messages and SLEE-to-switch : messages in a formal ASN.1 syntax form that is post-processed into specific GTD-5 EAX TCAP messages used in ~, conjunction with switch testing tools. In this way, call ~ 30 scenarios that have been verified on the BCMRP are then ; automatically compared with the actual switch operation.
` Although the preferred embodiment of the invention . has been illustrated, and that form described, it is readily apparent to those skilled in the art that various 35 modifications may be made therein without departing from the spirit of the invention or from the scope of the appended claims.
.~
.~

" ~

: i .

, . . ,~, . , . ~

tv Submachine *************************************************
\ * COPYRIGHT(C) 1991-1993 AG COMMUNICATION SYSTEMS CORP. *
\ *****************************************~***************

--_ ----____________________________ \0 Actv -- Originating Actlve PIC Submachine user O.Actv : O.Actv.NI ( -- ) O.Actv @ Response->NOT-IMPLEMENTED ;
: O.Actv.response>> ( -- _ O.Actv @ response>> ;
0.Actv submachine >0.Actv states Awaiting_Event.09 Call Terminated.09 Cleared.09 Disconnected.09 Feature Requested.09 Leg_Attached.09 Operation_Failure.09 Operation Success.09 Reconnected.09 Sw_Contextual Failure.09 ; 25 Timeout_Occurred.09 end-states : O.Actv.ELSE ( InputToken -- ) dup events =
if drop Awaiting_Event.09 O.Actv set-state >>event>>
else O.Actv @ Awaiting_Event.09 @ @ =
if O.Actv @ or-else.prompt else O.Actv @ ProcessIntOrQevent then then ;
!

state Awaiting_Event.09 Call_Terminated Call Terminated.09 ~ 0.Actv.response>>
Cleared Cleared.09 { 0.Actv.response>>
Disconnected Disconnected.09 { 0.Actv.response>>
Feature_Requested Feature_Requested.09 ( 0.Actv.response Leg_Attached Leg_Attached.09 { 0.Actv.response>>
Operation_Failure Operation_Failure.09 { 0.Actv.response>>
Operation_Success Operation_Success.09 { 0.Actv.response>>
Reconnected Reconnected.09 { 0.Actv.response Sw_Contextual Failure Sw_Contextual_Failure.09{ 0.Actv.response Timeout_Occurred Timeout_Occurred.09 { 0.Actv.response - or-else Awaiting Event.09 { 0.Actv.ELSE
state Call_Terminated.09 Continue Awaiting_Event.09 { Call_Terminated_Ack.act ) ' or-else Call_Terminated.09 { 0.Actv.ELSE ) state Cleared.09 Analyze_Route Awaiting Event.09 { Analyze Route.act ) Continue Awaiting_Event.09 { Cleared_Ack.act ) Disconnect Awaiting_Event.09 { Disconnect.act ¦
Ignore_Event Awaiting_Event.09 { Ignore_Event.act Move Leg Awaiting_Event.09 { Move Leg.act or else Cleared.09 { 0.Actv.ELSE
state Disconnected.09 Continue Awaiting_Event.09 { Disconnected_Ack.act Disconnect .~waiting_Event.09 ~ Disconnect.act Ignore_Event Awaiting_Event.09 1 Ignore_Event.act : .. ~ .. ..... ... . . .. . . .... . . . . .

:, . ...
.` `: . : ... . .
.... ~ . . ...

,i 2~22182 Move_Leg Awaiting_Event.09 ( Move_Leg.act or_else Disconnected.09 ~ 0.Actv.ELSE
,:; state Feature_Requested.09 ;/ 5 Continue Awaiting_Event.09 ~ Cont.Feature_Requested.act }
Disconnect Awaiting_Event.09 ~ Disconnect.act ) ~; Ignore_Event Awaiting_Event.09 ~ Ignore_Event.act Move_Leg A~aiting_Event.09 ~ Move_Leg.act }
or-else Featue_Requested.09 ~ O.Actv.ELSE ) ~` state Leg_Attached.09 General_Ack Awaiting_Event.09 ~ General_Ack.act }
Continue Awaiting_Event.09 ( General_Ack.act ~i or-else Leg_Attached.09 ~ O.Actv.ELSE I
'-; 15 state Operation_Failure.09 Continue Awaiting_Event.09 ~ Operation_Failure.act or-else Operation_Failure.09 ~ O.Actv.ELSE I
20 state Operation_Success.09 ( only generated in response to a Move_Leg ) Continue Awaiting_Event.09 ~ General_acX.act }
~' Disconnect Awaiting_Event.09 ~ Disconnect.act ) ', General_Ack Awaiting_Event.09 ~ General_Ack.act ¦
~j Ignore_Event Awaiting_Event.09 ~ Ignore_Event.act or-else Operation_Success.09 ~ O.Actv.ELSE
~ state Reconnected.09 '', Continue Awaiting_Event.09 ( Reconnected_Ack.act or-else Reconnected.09 ~ O.Actv.ELSE
~` 30 state Sw_Contestual_Failure.09 Continue Awaiting_Event.09 ~ Sw_Contextual_Failure.act ) .~; or-else Sw_Contextual_Failure.09~ O.Actv.ELSE ~
,., ',;J 35 state Timeout_Occurred.09 Disconnect Awaiting_Event.09 ~ Disconnect.act General_Ack Awaiting_Event.09 I General_Ack.act '~ Move_Leg Awaiting_Event.09 ~ ~ove_Leg.act ' or-else Timeol~t_Occurred.09 ~ O.Actv.ELSE ) ,, 40 end-submachine .~
. .
.~, .
~ Table 1 ~, , . .
n, ';
:, :, ':
:
.~
'`

. .
i .. ': ~ ` . ~:
~., . ` `

21~182 ~ abulary = ool ( contains user~level 200L words ) __________________________________________________________________ !! DMAXæ assign: longalign private:
,~ (ool) DUMP assigns: longs: public:
: 5 .. ............DUNMAXE becomes: m: short:
.bname INIT binding-set: member-of: shortalign ;binding-set LIST-METHODS byte: method-is: shorts:
il ;class MPKE bytes: method: subclass:
;m NAME class-is: mexit ubyte:
: 10 ;subclass PRINT class-of: mrecurse ubytes:
;union REVEAL class: oa ulong:
?bname SIZE dcm obj-handle: ulongs:
?method: T.bname index-of object: union:
@@ alias: is-bound? objects: ushort:
. 15 ADDR aliases: late-binding; pointer: u~horts:
CLASSO: assign-type: long: pointers: with:
CONCEAL
: #WORDS = 71 ~.
, Table 2 ., Summary of 200L user words ----- -------------__________________________________ ool ( -- ) ( ool user word vocabulary; [defined in forth vocabulary] ) (ool) ( -- ) ( vocabulary for internal 200L words ) , i ,-;
Table 3 ~;
..
.
.
., ~ c . . .

.
.
, .

., .

:i . .
....
,, .
;.
~ -56-.
,:~
. .

21~21~2 abulary - (ool) ( contains internal 200L words not normally accessed by user ) #deferred +hdr-cfa b->l modified-hdr , '(;)active-descriptor +mf-genword balance mrd-descr-node ! 5 '(colon) +mf-index binding-table+dn-target msmudge '(constant) +mn-branch binding-type oa '(create) +mn-index bt-error old-cfa 'oh->addr +mn-link(CONCEAL) build-binding-template print_general i 'oh->type +mn-list byte_dump ptr_dump 10 ((DMAXE)) +mn-target byte_print ptr_size_of ((MAKE)) +mn-zero conceal public-flag ((conceal)) +sd-subclass ctime recurse-dlist I ((reveal)) +sno-body curr-class redirect-header (ADDR) +sno-call curr-elt resolve-binding-set 15 (DMAKE) +sno-descriptor current-binding-set restore-header (DUMP) +sno-does> deferrals-list reveal (DUNMAKE) +sno-link-to-name describe-object s->l (INIT) +subclass-link descriptor set-oa (LIST-METHODS) +subclass-li~t descriptor-node set-oa-trace 20 (MAKE) .descr dno short_dump (NAME) .dnode dump_general short_init.mnodes (PRINT) .dnodes element short_make (REVEAL) .mnode element-error short_print (SIZE) lsdmp elt-method: short_size_of ~ 25 (bind-it) ludmp generic-word sno-head i (binding) 22id.r immediate-method subclass-descriptor ~ (class-is) 2sdmp init-bt-ntry tracingon j (conceal) 2udmp init_general ubyte_dump (is-bound?) 32id.r legal? ubyte_init 30 (method-is) 4sdmp link-deferred-method ubyte_make (reveal) 4udmp list-methods_general ubyte print +class-size ADDROF long_dump ubyte_size_of +dn-array-multiple BYTE long_print uid#
+dn-link DEBUGGING make-descr-node ulong_dump ~ 35 +dn-list LONG make-method-nod ulong_init J +elt-descrnode POINTER make-sno-hdr ulong_make +elt-genword SHORT make-snol ulong_print , +elt-methform UBYTE match-bindings ulong_size_of +elt-methnode ULONG method-format unique-id#
~, 90 +gw-cfa USHORT method-node ushort_dump ~ +gw-does [']oh.addr methods-error ushort print ,~ +gw-header [']oh.type mlink validate-descr :~ ______________________________________________________________________________ ~ #WORDS = 165 ,i . .
gs Table 4 .

, .

.
i' ,, , -57-:
2122~2 SSO: METHODS - inherited by any new 200L class t _ _ _ _ -- _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ; I !! ( value 'element -- ) ( store value according to element type ) ; I @@ ( 'element -- value ) ( read value to stack with sign extension when `, 5 appropriate ) I ADDR ( 'obj 'descr -- 'object ) - I CONCEAL ( 'obj 'descr -- ) ( conceals all the methods of the class and its subclasses ) I DMAKE ( 'obj 'descr -- 'obj ) ( makes a dynamic instance of a class ) 10 I DUMP ( 'obj 'descr -- ) ( recursive object dump ) I DUMMAKE ( 'obj 'descr -- ) ( unmake a dynamic object instance ) ~ I INIT ( 'obj 'descr -- ) ( initialize an object ) ;; I LIST-METHODS ( 'obj 'descr -- ) ( list methods of object or class ) ~ I MAXE ( 'obj 'descr -- ) ( makes a static named instance of class ) 15 I NAME ( 'obj 'descr -- 'name ) ( returns name of object ) ~ I PRINT ( 'obj 'de~cr -- ) ( print object values ) :, I REVEAL ( 'obj 'descr -- ) ( recursively reveal all methods of class and its ' ,~ubclas3es ) I SIZE ( 'obj 'descr -- #bytes ) ( return size of object or class ) .~ 20 +-------------~, .. ( -- 'descr ) ~- \ a shorthand notation for specifying that at execution \ time, the value on stack will point to an object :~ \ whose TYPE is consistent with the class currently \ being defined ~ .bname ( -- ) ( <bname> ) ,: \ display class currently associated with binding name ,. T.bname ( 'tcb -- ) ( <bname> ) ,: \ display class currently associated with binding name i~ 30 ;binding-set ( bt cbs dl -- ) .,: ;class ( current-size -- ) ( terminate definition of class ) ''. ;m ( -- ) ( terminate m: definition ) 5,', ; subclass ( see subclass: ) `.`,' ;union ( see union: ) 5~' 35 ?bname ( a -- a ) \ error if not the cfa of a binding-set name .~ ?method: ( -- ,<name> ) :. assign-type: ( 'classobj 'descr -- , ~name> ) j \ assigns a class type to an obj-handle ~ ( usage: <classname> assign-type: <obj-handle-name> ) .:~ 90 becomes: ( 'obj -- ) \ associates dynamic object address with obj-handle :.:! ( usage: <classname> DMAKE becomes: <obj-handle-name> )`~, binding-set: ( <name> ) ( --- bt cbs dl ) ,~ class-of: ( -- ,obj-handle-name ) a dcm ( 'descr 'CLASSO -- ) ( <method-name> ) \ decompile a method ,i 45 is-bound? ( compiling: -- ) ( <method-name~ <binding-set-name> ) -` ( interpreting: -- flag ) ( <method-name> <binding-set-name> ) ,~ late-binding; ( -- ) ( sets up late binding via binding sets ) ~ obj-handle: ( -- , <name> ) ,~ \ defines a handle to be used for referencing dynamic objects alias: ( when defining: <classname> <alias-elt-name> --~; \ within a class data definition, creates a pointer to s \ an object of a particular clas~. An alias: type element must be ,~1 \ initialized using assign:
ol aliases: ( when defining: <count> <classname> <alias-array-name> --,'.~ 55 \ within a class data definition, creates an array of pointers to an \ object of a particular class. An aliases: type element must be ~ \ initialized using assigns:
: assign: ( 'obj oa <alias-elt-name> -- ) \ assigns val to <alias-elt-name>
~: ( usage: <obj-name> ADDR assign: <alias-elt-name>
( <alias-eltname> behaves as object of class specified by alias: ) ~ assigns: ( 'obj <index> oa <alias-array-name> -- ) `.~ \ assigns val to <alias-array-element>
~:. \ usage: <obj-name> ADDR <index> as,~igns: <alias-array-name>
\ <alias-array-element~ behaves as object of class specified by alias:
~:~ 65 byte: ( <eltname> -- addr ) bytes: ( count <eltname> -- addr ) ~.:
:,, . ., .
.~
." -58-lass-is: ( -- ) ( <class-name> ) : \ used to defer evaluation of method/class \ when class is known at compile time but method is not Xnown class: ( <Class-name> -- 0 ) index-of ( <method-name~ -- u ) \ returns index value of a method long: ( <eltname> -- addr ) longa~ign ( offset -- offset' ) \ aligns with long word boundary longs: ( count <eltname> -- addr ) m: ( <method-name> ) \ define action for a method member-of: ( <cla~sname> ) method-is: ( -- ) ( <method-name> ) \ used when the method is known at compile time but the class is not \ known. Has the effect of deferring evaluation of the method-index \ until execution time method: ( -- ) ( <name> ) \ define (or redefine) a method name ?method: ( -- ) ( <name> ) \ conditionally define a method name, if it does't exist mexit ( -- ) \ restore previous value of oa and return oa ( -- 'obj ) \ returns pointer to current object object: ( <eltname> -- addr ) ( when defining: <cla~sname> object: <eltname> ) i objects: ( count <eltname> -- addr ) ( when defining: count <classname> object: <eltname> ) pointer: ( <eltname> -- addr ) pointers: ( count <eltname> -- addr ) private: ( -- ) \ set following definitions within class to be private public: ( -- ) \ set following definitions within class to be public j short: ( <eltname> -- addr ) shortalign ( offset -- offset' ) \ aligns with even byte boundary ; 30 shorts: ( count <eltname> -- addr ) ; subclass: ( subclass: <subclassname>
( subclass data and method definitions ) I ( see ;subclass ! ubyte: ( <eltname> -- addr ) . 35 ubytes: ( count <eltname> -- addr ) ulong: ( <eltname> -- addr ) ulongs: ( count <eltname> -- addr ) ' union: ( <classnameX> union: <eltnamel>
( <classnameY> with: <eltname2>

( <classnameZ> with: <eltnameN>
( ;union i ushort: ( <eltname> -- addr ) ~i 45 ushorts: ( count <eltname> -- addr ) with: ( see union: ) : ------_ _ _ _ _ _ _ _ _ _ _ _ Table 5 il ., ., ~ 59-~: .

.~.*********************************.~*****,~.****",***********
~ COPYRIGHT(C) l991-1993 AG COMMUNICATION SYSTEMS CORP. *
\ *********************************************************
only forth definitions O cload task-200L
~ 5 create task-200L \ dummy word for ?include check : vocabulary ool \* stack~
\* defined in: forth \* category: 200L
\* topic: class definition \* description:
__ __ ___________+
\* I ool is the name of the vocabulary for user-oriented 200L words. The ool vocabulary I
i \* I is also used as the vocabulary for all method names defined for any classes, both I
\* I pre-defined classes that are part of the 2001box platform and new classes defined I
\* I as part of an application program. There is also an internal (ool) vocabulary I
\* I which contains words used internally by other 200L words. These should not I
\* I normally be used by someone using 200L as a programming language.
~, \ ---- --__ ___ ______________________+
~ 20 ;~ also ool definitions i vocabulary (ool) \* stack: ( -- ) i~ 25 \* defined in: ool ,, \* category: 200L
\* topic: class definition \* description:
:. \ + --------------_ _____ __________________________________________________+
\* I (ool) is a vocabulary for keeping the internal 200L implementation words separate I
\* I from the user-oriented words of the system. Words in (ool) should normally only be I
, \* I used or modified when changing or extending the 200L language. Also see ool. I
. --_ ________+
base @ hex also (ool) definitions ( determine the cfa value for a created word and store it in a constant ) : create tst ' tst @ forget tst constant '(create) `~ O constant tst ' tst @ forget tst constant '(constant) :1 40 ' ( define uid# --- a variable which identifies the last value of a methods ) '; ( index which has been previously assigned ) ~ create uid# O , .- 45 ( define curr-class --- a pointer which points to the class structure ) m ( of any class which is currently being defined ) ;.~ create curr-class O , ( define curr-elt -- a constant whose value points to the element ) , 50 ( currently being defined ) ~1 O constant curr-elt " ( define oa -- a constant which will normally point to the object which is ) ( being acted upon by a method ) 55 0 constant oa ~;.
,. ,~
. .
. .

....
,. ~
,'' :
::, .~.
s ~
.
.

212~ ~ ~2 - -l definitions (ool) - 'descr ) ( a shorthand notation for specifying that at execution) ( time, the value on stack will point to an object ) ( whose TYPE is consistent with the class currently ) ( being defined ) , curr-class @ ; immediate .'~ definitions :-' ( define active-descriptor -- a pointer to the most recently used ) ( descriptor ) create active-descriptor 0 , - ( define mrd-descr-node --- a pointer to the most recently defined ) ( descriptor node ) create mrd-descr-node 0 , ( define public-flag --- a flag which indicates whether the next method ) 1- ( to be defined ~hould be public or private. A TRUE value indicates ) ' ( that the method will be publically available; i.e., can be accessed ) ( outside of the 3cope of the class definition. ) i create public-flag 0 , ;r~ ( define public: and private: --- a couple of words whose effect is to set) ( or clear the value of public-flag respectively. Methods which follow ) ( the word public: will be publically accessible whereas those following) ( the word private: cannot be accessed outside the scope of the class ) ( definition. ) ool definitions (ool) : public:
----------------________________________+
::` \t I Sets mode within class definition so subsequent method definitions will be I
`~ \* I accessable outside the class definition. I
--------------______________________+

: private: ( -- ) ----------------________________________+
~* I Sets mode within class definition so subsequent method definitions will be I
\* I accessable only from within the class definition. I
\ + ----------__________________________________________+
i definitions ( The following define some of the major data structures used by OOL ) structure descriptor-node pointer: +dn-link ( pointer to next descriptor-node in list ) pointer: +dn-target ( pointer to as~ociated descriptor ) ; long: +dn array-multiple ( indicates number of copies in array ) ( n=-l => not an array ) ( all other n => number of copies ) structure.end ., , .

. .

i'~i -~, ':
~, ~,' :

~ , ;'.''i' ~ ' ,: ' , ~ ' 2122~2 ructure method-node pointer: +mn-link ( pointer to next method-node in list ) union~
long: +mn-index ( if <>0, gives index value of associated ) ( method ) pointer: +mn-target ( points to execution code for method ) )union{
long: +mn-zero ( when value is zero... ) pointer: +mn-branch ( points to inherited descriptor ) lunion structure.end structure descriptor pointer: +dn-list ( points to first entry in descriptor list ) pointer: +mn-list ( points to first entry in methods list ) long: +class-size ( 3tatic size of object being defined ) pointer: +subclass-list ( points to list of associated subclasses ) structure.end structure subclass-descriptor descriptor struct: +sd-subclass pointer: +subclass-link structure.end structure sno-head pointer: +sno-descriptor ( points to associated descriptor ) pointer: +sno-link-to-name ( points to associated header ) pointer: +sno-does> ( field pointing to does clause ) ; pointer: +sno-call ( pointer to (does>) ; 30 long: +sno-body ( beginning of body of object ) structure.end structure generic-word pointer: +gw-header pointer: +gw-does ` pointer: +gw-cfa structure.end structure method-format generic-word struct: +mf-genword pointer: +mf-index structure.end structure element method-format struct: +elt-methform ~'j method-node struct: +elt-methnode descriptor-node struct: +elt-descrnode ~ generic-word struct: +elt-genword - structure.end : unique-id# ( -- u ) ( returns a unique number suitable for u~e as ) `~ : methods-error ( -- ) ( print an error message indicating that the ) ' 55 ( method and class are not compatible ) . ~
: element-error ( -- ) ( print an error message indicating that the ) ~ ( element name is not appropriate for the class ) `, ~:`

`:
,~, :,j '!
' `
' , -62-.~

, .. ... , ; ~ ~ ;.. ` , .. ` , .

.. , . . .. `, . ,. -. ` .. .: . ~

2~2~ 82 l definitions (ool) index-of \* I In 200L, method names are global and unique. Each one is associated with an index I
\* I value that must be bound to an actual code thread (defined using the m: word) I
\* I before it can be executed. index-of <method-name> returns the index value for any I
\* I defined method name. I
~ \ --------------------_____--___________________________+
definitions . : (method-is) ( 'obj 'descr index -- ) ( performs a deferred search of ) -~ ( the methods list at execution time ) ool definitions (ool) '~ : method-is:
+ ----------------------------____----___________________________________+
\* I method-is: i5 u3ed when the method is known at compile time but the class i9 not I
\* i known. Has the effect of deferring evaluation of the method-index execution time. I
\* I See the system help on 200L late-binding for more information. I
~ \* I Example:
`- \* I : test.method-is: ( -- ) 'testobj test.descriptor method-is: DUMP ;
; \ + ------------ ________________________________________________+
.~
; 25 definitions - : (class-is) ( 'obj index 'descr -- ) ( performs a deferred search of ) ( the methods list at execution time ) ool definitions (ool) : class-is:
+ ------ --_____----___ ______________________________+
- \* I class-is: is used to defer evaluation of method/class when class is known at I
\* I compile time but method is not known. I
` 35 \* I See the system help on 200L late-binding for more information. I
\* I Example:
~ \* I : test.class-is: ( -- ) 'testobj index-of DUMP class-is: TestClass: ;
:~ ~ \* I
:: \ ---- ----------___----_____________________+
find ?dup ~ if ( the class name was found.... ) i-: >body +sno-body state ~
if ( compiling... ) [compile] literal compile (class-is) exit '~ then ( not compiling.... ) . (class-is) exit :~ then ( class name was not found.... ) :~ cr ." ool: class-is: could not find class name " 105 throw ; immediate -~ definitions ~ 0 constant old-cfa ( saves previous value of a header's cfa ) :;~`! O constant modified-hdr ( saves address of modified header ) ~ : +hdr-cfa 028 + ;
!~.p, 55 : restore-header ( -- ) old-cfa ?dup , if ( a header has been tampered with.... ) modified-hdr +hdr-cfa ! 0 is old-cfa ~, then ;
redirect-header ( cfa 'hdr -- ) ( redirect a header to point to a new cfa ) ( the previous cfa of the header is saved in old-cfa ) `1~ restore-header .' dup is modified-hdr +hdr-cfa dup Q is old-cfa ! ;
, ~
, ~:, ; -63-:

~: :

2122~82 The following code creates the first part of a static named object ) make-snol ( <sno-name> 'descriptor -- ) create immediate ( create the object name and make it immediate ) , ( save its descriptor address ) here 10 - @ , ( compile a pointer to its pseudo header ) 0 , ( compile 0 for its "does>" field ) '(create) , ( compile create as its cfa ) ;
: make-sno-hdr ( <sno-name> 'descriptor -- ) ' make-snol i does>
dup @ ( addr 'descr ) - swap Oc + ( 'descr cfa ) state @ ( 'descr cfa state ) if ( compiling... ) ( 'de3cr cfa ) , ( compile the cfa ) ( 'descr ) l else ( interpretting.... ) ( 'descr cfa ) execute swap ( pfa 'descr ) ' 20 then J also ool definitions ( The following code creates the basic skeleton for CLASS0: ) 0 make-sno-hdr CLASS0: restore-header (ool) definitions previous r~ here ' CLA5S0: >body ! ( patch descriptor of CLASS0: to be itself ) 0 , ( list of descriptor nodes, to be patched up later ) 0 , ( list of methods nodes, to be patched up later ) 10 , ( size of objects belonging to CLASS0: --- sixteen bytes ) 0 , ( list of subclasses, there won't be any ) : validate-descr ( 'descr -- 'descr ) dup body> [ ' nucleus ] literal over u< ( 'descr cfa-descr FLAG ) over here u< and ( 'descr cfa-descr FLAG ) ~, 35 if ( so far, it lies in a reasonable range of addresses.... ) ( 'descr cfa-descr ) '(create) = ( 'descr FLAG ) over q cells - @ CLASS0: [ drop ] = and if exit then then ( looks like we're in trouble... ) cr ." 200L: invalid descriptor " u. 106 throw ;
ool definitions (ool) also decompiler , : dcm 1 45 \ + -- -----_ _ ___________________________+
l \* I Decompile a method. Example usage:
~ \* I <myclassname> dcm <methodname>
---- -- _------------____________________________+

i`, ~, i:
., "
,;~
.;

i, ~i -64-. .

2122~82 ~ethod:
\* I method- is used to define a unique method name that may be used in multiple I
\* I classes. method names are forced into the ool vocabulary, and associated with a I
\* I method index that is bound to a specific code thread defined within each class I
\* I using the m: word. Also, see the ?method: word. I
\* I Example usage:
\* I method: <methodname>
+ ------------____________________________________________+

method: MAKE
-- --_--------_____________________________+
\~ I This method makes a static named object of the specified class. I
\* I Usage: <classname> MAKE <objectname>
\ + - --------------__________________________________________+
method: CONCEAL
---- ___----____________________________+
\* I This method is used to conceal the private methods of the specified class. This I
\* I would normally be used following the use of REVEAL. This is normally used for I
\* I debugging. I
\* ¦ Usage: <classname> CONCEAL
-- _----------________________________ __+
method: REVEAL
-- __------________________________+
\* I This method is used to reveal the private methods of the specified class. This I
\* I would normally be used for debugging. I
\* I Usage: <classname> REVEAL
30 \ +-------____---____________________________+
method: DM~KE
____--___________________________+
\* I This method makes a dynamic instance of the specified class. It has no name, and I
\* I only its object address is returned. Normally an obj-handle: will be used to I
\* I reference the object. I
\* ¦ Usage: <classname> DMAKE
-- ____--______________________+
~;~ 40 method: DUNMAKE
., \ ________________________________+
; \* I Thi~ method destroys a dynamic object and returns its memory resources to the I
\* i operating system memory manager. I
-~45 \* I Usage: <obj-handle name> DUNMAKE
\* I or assuming 'obj is on stack: member-of: <classname> DUNMAKE
" \ --------------_------______________________+

method: INIT
50 \ + - ------____---___________________________+
\* I This method is used to initialize an object. Unless redefined for a specific I
,~ \* I class, the default INIT will zero the information elements of an object. I
,' \* I Usage: <objectname> INIT
~:~ \* +____________________________________________________________________________________+
' 55 ~` -65-- ,~` 2122~2 ~hod: @@
+___________________________________________________________________________ ________+
\* I This method will fetch the contents of an information element. It is I
\* I type-sensitive, and will perform sign extension for signed objects shorter than 32 1 \* I bits. Values are fetched to a single 32-bit cell of the forth parameter stack. I
\* I Usage: (within m: definition) oa <elementname> @@
~ --_______________+
-:
I method: !!
\ + -------------------- ___________________________________________+
\* I This method assumes a value i3 on the forth parameter stack. It will store the I
\* I value into the referenced object information element. If the element is shorter 1 \* I than 32-bits, the value will be truncated, if necessary, to store the value I
\* I without overwriting adjacent data. I
\* j Usage: (within m: definition) ( valueonstack ) oa <elementname> !!
, \ __ _ ___________+
~ method: SIZE
______ ______________+
\* I This method returns the static size of an object. It does not calculate the total I
\* 1 storage associated with a complex object that may consist of a chain of linked I
\* I objects unless it has been specifically redesigned to do so within the particular I
\* I object class.
I \* I Usage: <objectname or classname> SIZE
\ + - --------- -------------_------_________________________________+
method: ADDR
---- __ ______________________+
:~1 \* I This method returns the address of an object. I
~ 30 \* ¦ Usage: <objectname> ADDR
+ -------- ___------___________________________________+
:,...
method- DUMP
\* I This method performs a formatted dump of an object, listing the related I
` \* I information element names. I
\* I Usage: <objectname> DUMP
"..... ... , \ ---- _________________________________+
-` 40 method: PRINT
:, \ + -------- ________________________+; \* I This method simply prints out the values of the information elements of an object I
\* I with no symbolic information provided. This method is expected to be redefined I
\* I within each class to provide a formatted display of the object according to the I
;~j 45 \* I requirements of the application program being developed. I
~ \* I Usage: <objectname> PRINT
--_----_____________________________+
:, ; method: NAME
., 50 \ + _____--_ ________________________________+
-~*; \* I This method will return a pointer to the count byte of the name string for the I
:~ \* I object. I
- \* I Usage: <objectname> NAME
\* I or assuming the address of the object is on the stack:
55 \* I member-of: <objectclassname> NAME
---------- -- _ _________________+

~ ;
;
,:

, "~, ;,"

~hod: LIST-METHODS
+____________________________________________________________________________________+
\* I This method will list the method names defined for the specified class, or for the I
\* I class of the specified object. I
1 5 \* ¦ Usage: <object or class name> LIST-METHODS
------ _--_------_____________________________+
definitions : mlink ( cfa -- ) ( <method-name> ) ( create methods node and link ) ( to current class ) curr-class @ +mn-list here over @ , swap !
find >body @
public-flag @ or , ( get the index of the methodname and compile it ) ,;
: immediate-method ( -- ) ( make the immediately preceding method immediate ) ~ here method-node - +mn-index dup ~ ( 'index index ) i Offfffffe and ( get rid of the public bit ) negate ( mark it as immediate ) public-flag @ or ( OR back in the public bit ) swap ! ; ( store it back in the methods node ) ool definitions (ool) : obj-handle: ( <name> -- ) \ + -------------_____-_____ ___________________________________+
\* I Static Named Objects may be manipulated by name. The name carries with it the I
\* I object's address and its class. Dynamic objects do not have names, and have only I
\* I an address. obj-handle: will define a static named element that can be assigned I
\* I the class of objects it is supposed to be a handle for. this is done using the I
\* I assign-type: word. The object handle is assigned the address of an object using I
\~ I the becomes: word. Typically, an object handle will be assigned a class type only I
\* I once when it is defined, and then be attached to dynamic object addresses I
\* I dynamically. Typical usage:
\* I object-handle: <myclasshandlename>
\* I <myclass> assign-type: <myclasshandlename>
\* I <myclass> DMAKE becomes: <myclasshandlename>
------ ___________________________+
_j : becomes:
. 40 \ + - -------___----___________________________________+
~ \* I becomes: is used to assign an object address to an object handle. See obj-handle:
i, \~ I Typical usage:
\* I object-handle: <myclasshandlename>
\* I <myclass> assign-type: <myclasshandlename>
\~ I <myclass> DMAKE becomes: <myclasshandlename>
;~ \ -- ----------__--_--_______________________+
i~i , ~ .
~, . .
A, ~1 ., ~
~' .

. .
' . ~ .

2~22182 ~ssign-type:
stack: ( 'descr 'descr-descr I 'descr-descr ) \* defined in: ool \* category: 200L
\* topic: dynamic objects \* description:
:: \ +____________________________________________________________________________________+
\* I assign-type: i9 UAed to assign a cla~s de3criptor to an object handle. See I
\* I obj-handle:
\* I Typical usage:
\* I object-handle: <myclasshandlename>
-~ \* I <mycla~s> assign-type: <myclasshandlename>
` \* I <myclass> DMAKE becomes: <myclasshandlename>
+____________________________________________________________________________________+
drop ( 'descr I -- ) find ?dup if ( name was found... ) dup 4 cells +
@ '(constant) =
~ 20 if ( it looXs like an object handle.... ) `` >body ~i state @
;; if ( we're compiling.... ) ( 'body ) [compile] literal compile !
25 else ( we're interpreting.... ) ( 'descr 'body ) then exit then ( it doesn't look like an object handle... ) ~ cr ." assign-type: following word is not an object handle "
L, 30 then 108 throw ; immediate ~ : class-of:
---------- ___________________________+
;, \* I This word returns the class descriptor ('descr) for the class that is currently I
\* I assigned to the named object handle. I
i, \ + ------ _______----___________________________________________________+
. definitions : 'oh->addr ( 'obj-handle -- 'obj-handle-address-cell ) >body ;
~x~l qO : 'oh->type ( 'obj-handle -- 'obj-handle-type-cell ) [ f cells ] literal + ;
' : ['~oh.addr ( -- 'addr, <obj-handle-name> ) [compile] ' >body ; immediate ~-I : [']oh.type ( -- 'type, <obj-handle-name> ) [compile] ' [ 5 cells ] literal + ;
immediate ~; 45 ( Define tracingon -- a flag which if TRUE cause~ recurse-dlist to output ) .,~ ( tracing information as it recurses through the descriptor list ) O con~tant tracingon '~ : 32id.r ( cfa -- ) Oa cells - >name count lf and 20 over - 3 max 3paces type ;
: 22id.r ( cfa -- ) 5 cells - >name count lf and 16 over - 1 max spaces type ;
,' 50 .
~:, ., ., !
.':', ' ~' .
'`~
. ~
: ', '' :-`,',.
.,, '' . .
.':
`, ` : :

lse constant DEBUGGING immediate recurse-dlist ( 'obj 'descr index -- ) rot ?dup if >r else cr ." >>00000000 invalid object address for "
drop @ CELL - @ 32id.r exit then begin ( 'dnode index ) swap @ ( index 'dnode ) ?dup ( index 'dnode 'dnode I index O ) DEBUGGING iftrue cr ." dumping dnode (maybe)..." .s cr ifend while ( not at end of descriptor li3t... ) ( index 'dnode ) dup +dn-array-multiple Q ( index 'dnode array-mult ) ~, dup l+ ( index 'dnode array-mult array-mult+l ) ( an array-mult == -~ indicates it i9 not really an array ) j if ( it is an array.... ) ( index 'dnode array-mult ) DEBUGGING iftrue cr ." think it's an array??!" .s cr ifend ?dup ( index 'dnode array-mult array-mult I ) ' ( index 'dnode O ) if ~ the array is not empty... ) ( index 'dnode array-mult ) r> swap O ( index 'dnode 'obj array-mult O ) do ( index 'dnode 'obj ) 2dup ( index 'dnode 'obj 'dnode 'obj ) i swap rot ( index 'dnode 'obj i 'obj 'dnode ) 14 + ( index 'dnode 'obj i 'obj 'method ) tracingon if ( tracing i5 enabled... ) ( index 'dnode 'obj i 'obj 'method ) dup cr 32id.r 3 pick ." [ " u. ." ] " ( index 'dnode 'obj i 'obj 'method ) then ( index 'dnode 'obj i 'obj 'method ) execute ( index 'dnode 'obj 'elt I index 'dnode 'obj O ) ~- ?dup tracingon O= or if ( index 'dnode 'obj 'elt ) ; 20ver ( index 'dnode 'obj 'elt index 'dnode ) +dn-target @ ( indexs 'dnode 'obj 'elt index 'descr ) ,~ tracingon if dup 22id.r 2 spaces then active-descriptor Q >r dup active-descriptor !
validate-descr match-method ( index 'dnode 'obj 'elt cfa ivalue I ) 1 90 ( index 'dnode 'obj 'elt O ) ~, if ( we found a match.... ) ( index 'dnode 'obj 'elt cfa ) ; execute ( index 'dnode 'obj ) else ( no match... ) ( index 'dnode 'obj 'elt O ) 2drop ( index 'dnode 'obj ) ~ 45 then ( index 'dnode 'obj ) ;~ r> active-descriptor !
~i else e~ tracingon if Ob spaces ." NULL OBJECT" then then ~i 50 loop ( index 'dnode 'obj ) >r ( index 'dnode ) then ( index 'dnode ) else ( it is not an array.... ) ( index 'dnode array-mult ) DEBUGGING iftrue cr ." figured out it's not an array!" .s cr ifend drop rQ ( index 'dnode 'obj ) over 14 + ( index 'dnode 'obj 'method ) tracingon if dup cr 32id.r 2 spaces then ( index 'dnode 'obj 'method ) ~; DEBUGGING iftrue cr ." ready to compute the address..... " .s cr ifend execute ( index 'dnode 'elt I index 'dnode O ) DEBUGGING iftrue cr ." here's the address..... " .s cr ifend ?dup tracingon O= or if ( index 'dnode 'elt ) O 20ver ( index 'dnode 'elt O index 'dnode ) +dn-target Q ( index 'dnode 'elt O index 'descr ) tracingon if dup 22id.r 2 spaces then active-descriptor Q >r dup active-descriptor !

; -69-:

, ' ~ : : : ' : ' ~, -:. , : : . ~

validate-descr match-method ( index 'dnode 'elt 0 cfa ivalue I ) ( index 'dnode 'elt 0 0 ) if ( we found a match... ) ( index 'dnode 'elt 0 cfa ) 5 DEBUGGING iftrue cr ." ready to execute the method.... " .s cr ifend swap drop execute ( index 'dnode ) else ( no matching method... ) ( index 'dnode 'elt 0 ) DEBUGGING iftrue cr ." couldn't find a method" .s cr ifend drop drop ( index 'dnode ) then r> active-descriptor ! ( index 'dnode ) else ( index 'dnode ) tracingon if Ob spaces ." NULL OBJECT" then then then ( index 'dnode ) ' swap ( 'dnode index ) DRBUGGING iftrue cr ." ready to take another pass" .s cr ifend ' repeat ( index ) r> 2drop ;
: print general ( 'obj 'descr -- ) - [ index-of PRINT ] literal recurse-dlist ;
, : ctime ( cfa -- ) create ., , does> ( 'obj addr I addr -- ) @ state Q ( 'obj cfa state I cfa state ) if ( compiling.... ) ( cfa ) active-descriptor Q [compile] literal , else ( interpreting... ) ( 'obj cfa ) active-descriptor Q swap ( 'obj 'descr cfa ) `~ execute ,' then ;
~; 35 create dno ," DYNAMIC OBJECT"
: (NAME) ( sno-object-addr -- name-addr ) 3 '(create) over 4 - @ = >r 0 over 8 - Q = r> and !~ 40 \ if ( this is a static named object ) body> >name \ circumvent hash problem ;l if ( this is a static named object ) 5 cells - >name ~ else drop dno then ;
'~ : ADDROF ( object-addr -- descriptor-addr ) , 45 Y' ' print_general ctime (PRINT) . : dump general ( 'obj 'descr -- ) l [ index-of DUMP ] literal tracingon >r i-i 50 1 is tracingon recurse-dlist r> i9 tracingon ;
' dump_general ctime (DUMP) : init general ( 'obj 'descr -- ) , [ index-of INIT ] literal recurse-dlist ;
' init_general ctime (INIT) ~ 60 : (SIZE) ( descriptor-addr -- size ) ,~ active-descriptor Q
CLASS0: [ drop ] over =
if ( we're working on a class... ) ( 'descr ) state Q
65 if ( we're compiling.... t ( CLASS0: ) drop compile +class-size compile Q
.,.

, , .
; ' ~ -70-~`

2~2~82 , .
else ( interpreting... ) ( 'descr CLASS0: ) drop +class-size @ ( size ) then else ( we've got a regular object, not a class... ) ( 'descr ) state @
if ( we're compiling... ) ( 'descr ) compile drop +class-size @ [compile] literal else ( interpreting... ) ( 'obj 'descr ) ; +class-size ~ swap drop ( size ) : 10 then .~ then :~, -~ : ((M~KE)) ( 'descr -- ) .,, 15 dup make-sno-hdr restore-header +class-size @ allot align ;
- s : ( MA~ ) ( ---- ) ~ index-of MAKE state @
,~i if ( compiling ) here CELL - @ >body ( index 'descr ) else over then validate-descr match-method ( addr true ) ~ if [ hidden ' (M~KE) (ool) ] literal over '~~ if ( special ) state Q if , else execute then else ( normal ) drop ~tate @ if compile ((M~KE)) else ((MAXE)) then then exit then methods-error ;
: ((DM~KE)) ( 'descr -- 'obj ) +class-size @ get-memory ;
.~ : (DM~KE) ( --'~ 30 index-of DMAKE state @
if ( compiling ) here CELL - @ >body ( index 'descr ) else over then ': validate-descr match-method ( addr true ) if [ hidden ' (DMAKE) (ool) ] literal over - 35 if ( special ) state @ if , else execute then .~ else ( normal ) drop state @ if compile ((DMAKE)) else ((DMAKE)) then then exit then methods-error -~' , j 90 : (DUNMAKE) ( 'obj -- ) cr ." PRIMITIVE DUNMAKE OF OBJECT: " dup . cr ?dup if release-m then ( else it is a NULL object ) ;
: list-methods general ( 'descr -- ) ( display the methods associated with a descriptor ) +mn-list ( 'mn-head ) begin ( 'mn-head ) ' @ ?dup ( 'mnode 'mnode I 0 ) ` while ( 'mnode ) dup +mn-index @ ( n'mnode index ) ~if ( this is a normal methods node...... ) ( 'mnode ) 1 50 dup +mn-target ~ ( ' mnode cfa ) i cr id. ( display the method ) ( 'mnode ) 1~ else ( this is a link to another class.. ....) ( 'mnode ) I` dup +mn-branch @ ( 'mnode 'descr ) ~ recurse ( 'mnode ) `~ 55 then ( 'mnode ) ` repeat ; (LIST-METHODS) ( 'descr-descr I 'descr 'descr-descr I 'descr I 'obj 'descr ) active-descriptor @ CLASS0: [ drop ] over =
~ 60 if ( classname .. ) ( 'descr-descr I 'descr 'descr-descr ) `~ drop state @
if ( compiling.. ) compile list-methods_general ,;else ( interpreting.... ) list-methods_general then . .
., ~':
~, :, .
'. ' ~, . .

. ~
" , . , ,., , ~ , ' ; : ~ ! ' .: ~ ' , .

' " ' ' ~ ,, ': ' :

2122~ 82 else ( objectname.... ) ( 'descr 1 'obj 'descr ) state ~
if ( compiling... ) ( 'descr ) ; [compile] literal compile list-methods_general compile drop else ( interpreting ) ( 'obj 'descr ) list-methods_general drop then then;
: (ADDR) ;
( The following code is used to define a new class ) ool definitions (ool) : class:
_----------_____________________________+
\* I This i9 the defining word to begin the definition of a new object class. See the I
I \* ¦ system help on 200L for more information. I
__--__--__________________________+

: subclass:
_----------_____________________________+
\* I This is the defining word to define a new subclass. A subclass is like a class, I
\* I except its name can be made private within a class definition. I
\ + ----------------______-___________________________________+
:~ definitions , : ((conceal)) ( 'mlist-head -- ) : ( conceal takes all of the methods nodes belonging to an m-list and ) ( sets bit-l of all of those nodes whose "public bit" has not been set ) begin @ ?dup ( 'mnode I 0 ) while ( 'mnode ) dup +mn-index dup ~ ( 'mnode 'index index ) ' 35 ?dup ( 'mnode 'index index index I 'mnode 'index 0 ) -i if ( 'mnode 'index index ) I dup 1 and ( 'mnode 'index index public-bit ) ~i. if ( 'mnode 'index index ) 2drop ( 'mnode ) ;. 40 else ( 'mnode 'index index ) i:, 2 or swap ! ( 'mnode ) ~' then ( 'mnode ) ;~ else ( 'mnode 'index ) i~ drop ( 'mnode ) 3 45 then ( 'mnode ) repeat ;
~-~ : (conceal) ( 'descr -- ) ( conceals all the methods of all the subclasses belonging to the ) ~ 50 ( subclass list associated with this descriptor ) ! . +subclass-list ( 'subclass ) begin ( 'subclass ) ?dup ( 'subclass 'subclass I 0 ) j while ( 'subclass ) ;~ 55 dup ( 'subclass 'subclass ) ~.~ +mn-list ( 'subclass 'mlist-head ) ;~ ((conceal)) ( 'subclass ) . +subclass-link ( 'subclass' ) '~ repeat ;

: conceal ( 'descr -- ) ( conceals all the methods of the class and it~ subclasses ) dup (conceal) ( conceal the subclasses ) :! +mn-list ((conceal)) ( conceal the class itself ) ~ 65 ':~

.
.j ~ .
,,.
, .

2 ~ 2 'CONCEAL) ( I 'descr ) : active-descriptor @ CLASSO: [ drop ] =
: if ( classname ..... ) ( I 'descr ) state @
if ( compiling .. ...) compile conceal el~e ( interpreting ... ) conceal : then exit 10 then ( objectname ) methods-error ;
: ((reveal)) ( 'mlist-head -- ) ( reveal taXes all of the methods nodes belonging to an m-list and ) , ( clear~ bit-1 of all nodes ) 3 15 begin 1 @ ?dup ( 'mnode I O ) while ( 'mnode ) dup +mn-index dup @ ( 'mnode 'index index ) Offfffffd and ( 'mnode 'index index' ) swap ! ( 'mnode ) repeat ;
I : (reveal) ( 'descr -- ) ( reveals all the methods of all the subclasses belonging to the ) ( subclass list associated with this descriptor ) +subclass-list ( 'subclass ) begin ( 'subclass ) @ ?dup ( 'subclass 'subclass I O ) . while ( 'subclass ) dup ( 'subclass 'subclass ) +mn-list ( 'subclass 'mlist-head ) ((reveal)) ~; +subclass-link I repeat ;
:
:', . .

.,~ .
,~
, ~, .
. ~ .
,, :

.

: , .~ :

2~22~2 `-eveal ( reveal reveals all the methods of a cla~s and its subclasses ) dup (reveal) ( reveals the subclasses ) +mn-list ((reveal)) ( reveals the class itself ) : (REVEAL) ( i 'descr ) active-descriptor @ CLASSO: [ drop ] =
'- if ( classname .... ) ( I 'descr ) ~', 10 state Q
if ( compiling... ) compile reveal ~' else ( interpreting.... ) ~¦ reveal ,~ 15 then exit then ( objectname ... ) methods-error ;
~ ( Now we attach the general methods to CLASSO: ) Ejl 20 CLASSO: drop curr-class ! ( set up CLASSO: as the current class ) "~ ' (ADDR) mlink ADDR
LJ ~ (CONCEAL) mlink CONCEAL immediate-method ~; ' (DMAKE) mlink DMAKE immediate-method f-l ' (DUMP) mlink DUMP immediate-method ,~` 25 ' (DUNMAKE) mlink DUNMAKE
' (INIT) mlink INIT immediate-method i ' (LIST-METHODS) mlink LIST-METHODS immediate-method ~1 ~ (M~KE) mlink MAKE immediate-method ' (NAME) mlink NAME
' 30 ' (PRINT) mlink PRINT immediate-method - ' (REVEAL) mlink REVEAL immediate-method ~ ' (SIZE) mlink SIZE immediate-method ;';
ool definitions (ool) ', 35 ~i : ;class :. \* +____________________________________________________________________________________+
i \* I This word ends the current class definition. See the syatem help on 200L for more I
\* I information. I
40 \ + -----------------__________________________________________+
.~
;` : ;subclass : \ + _______________________________________________________________________________+
\* I This word terminates definition of the current subclass. I
\ + - ---------___________________________________+
.. .
i~ : member-of: ( 'obj -- ) ( <classname> <methodname> ) \* +--------------------------------------------------------------------------------------------------------------------__________________________+
' \* I This word supports late binding of a class of an object whose address is on the I
;, 50 \* I stack. Example usage:
. \* I
:~ \* I : test.member-of: ( -- ) 'testobj member-of: TestClass: DUMP ;
\* I
, \* I See system help on 200L late-binding for more information. I
55 \ + ---------______________________________________+
definitions ~ !

"~
'.`.1 .

~ .
.
;:
,...

`.:
, -74-'~
,!~. :
.`. ~:

~ake-descr-node ( array-size 'descr <descr-node-name> -- ) elt-method: ( create the basic method ) ( now we create and initialize the elemental methods node ) method-node allot ( allocate the space ) ( link it into the methods list ) curr-class @ +mn-list @ curr-elt +elt-methnode +mn-link !
curr-elt ~elt-methnode +mn-link curr-class @ +mn-list !
( initialize the index value ) curr-elt +elt-methform +mf-index @
public-flag Q or i curr-elt +elt-methnode +mn-index !
~ ( initialize the target of the method ) :! curr-elt +elt-genword +gw-cfa curr-elt +elt-methnode +mn-target !
( now we create and initialize the elemen'cal descriptor node ) descriptor-node allot ( allocate the space ) j ( link it into the descriptor nodes list ) ¦ 0 curr-elt +elt-descrnode +dn-link ! ( 0 indicates end of list ) , curr-elt +elt-descrnode +dn-link dup mrd-descr-node @ ! mrd-descr-node 3 i ( initialize the target field ) i 20 curr-elt +elt-descrnode +dn-target !
~' ( initialize the array multiple ) curr-elt +elt-descrnode +dn-array-multiple !
, ( now we create and initialize the generic word for execution time behavior ) < generic-word allot ( allocate the space ) ( set up the header pointer ) curr-elt +elt-methform +mf-genword +gw-header @ curr-elt +elt-genword +gw-header ( set up the does field ) 0 curr-elt +elt-genword +gw-does !
( set up the cfa ) '(create) curr-elt +elt-genword +gw-cfa !
-~ ( now we redirect the header ) curr-elt +elt-genword +gw-cfa curr-elt +elt-methform +mf-genword +gw-header @ redirect-header ool definitions (ool) : shortalign ------------________________________________+
\* I As elements are being defined within a class'es instance data, the allocation I
\* I offset is being incremented by the size of each element. This word moves the I
~i \* I running offset up to the next 16-bit byte boundary. I
+ -------- -- _____________________________________________________________+
~i .
: longalign ~:! \* +--------------------- +
, \* I As elements are being defined within a class'es instance data, the allocation I
, \* I offset is being incremented by the size of each element. This word moves the I
~' \* I running offset up to the next 32-bit byte boundary. I
i:i ~ ~~~~~~~~~~~~~~~~~~-----------------------_______+

. .
,., ~, ; .
' ~j i: ~

.~, . .

:

~1221 82 ~lias:
+____________________________________________________________________________________+
\* I The alias: element type defines a pointer to a object whose type must be provided I
; \* I by a class name preceding the alias: word. This defines an element which behaves I
5 \* I as if the element were an object of the referenced class, rather than as a pointer I
\* I to the object. Typical usage: I
\* I SomeClassName: alias: +thisElementName \* I After a class using alias: definitions has been instantiated, the alias: elements I
~1 \* I need to be initialized using the assign: word. The assign: word needs an object I
10 \* I address on the stack for an object of the specified class, or a zero to initialize I
~ \* I the alias: pointer as a NULL pointer. Example of using alias:
., \* I
`! \* I <value> oa assign: <aliase:element>
! \* I
15 \* I Methods referencing alias: elements should normally test the address, using the I
\* I ADDR method, before referencing other methods of the aliased object. I
:. \ +____________________________________________________________________________________+
f : aliases:
20 \ + - ------_-___--__________________________________+
\* I The aliases: element type allows definition of an array of alias: pointers. Such I
\* I elements need to be initialized in almost the same way alias: elements are I
\* I initialized, but using the assigns: word instead of the assign: word. References I
~l \* I to arrays, require an index on the stack. For example:
25 \* I
\* I <value> <index> oa assigns: <aliases:element>
----------_____--___________________________+
: : assigns:
30 \ + --------------__-----___________________________________+
\* I Used to initialize an element of an aliases: array. See aliases:
.~ \ -- ------___----___________________________+
: assign:
\ + ---------------___-_--___________________________________+
\* I Used to initialize an alias: pointer. See alias:
~;I ---------- ______________________+
: mexit \ + --------__-----__________________________________________+
\* I Provides a way to exit from a m: definitioni equivalent to exit in : definition. I
------ __________ ________________+
, ~
; : ;binding-set \ + - ---------___----___________________________________+
\* I End definition of binding-set range. I
\* I binding-set:
:; \* I :m ml ...... ;m \* I :m m2 ... ;m : 50 \* I
: \* I . I
\* I :m mN ... ;m j \* I ;binding-set __----_________________________+
`- 55 : .-f , ~
,': ' ::' ....

., ~:~
d`
"' ."
: ' ~'f ,, ~
, . .

., . . .
, ~
.~;

2 ~ 8 2 ~inding-set \* I Begin definition of binding-set range. I
\* I binding-set: I
\* I :m ml ... ;m \* I :m m2 ... ;m \* I . I
\* I
\* I :m mN ... ;m \* I ;binding-set ~ \ -- --------------____------______________________+
~ : late-binding;
~; \* +____________________________________________________________________________________+
! 15 \* I Used to specify late-bound methods within m: definitions in a "template class". I
--------------____________________________+
' : is-bound?
. \ --------------_____________________________+
\* j Used to test whether a template class method has been bound to a specific class. I
.~: ------------------___________________+
~: ' ~ : m:
_----------______________________+
!' 25 \* I In 200L, method names are global and unique. However, they must take on a I
' \* I different specific meaning in relation to every class definition to which they I
\* I apply. This i9 called "method binding". m: provides the specific code thread for I
~ \* I each method as it applies to the class it is defined within. m: is the 200L I
I \* I equivalent to the regular forth : defining word. I
\ + --------_____----__________________________________________+
: ;m -- ________________________________+
\* I ;m terminates an m: method thread definition. It is roughly equivalent to ; for a I
35 \* I forth : definition. I
~, \ --_--------__________________________+
,;
` : mrecurse ( 'descr -- ) ( recursively reenter the current method ) --__------__________________________+
\* I Used to recursively enter the current method definition .~, \ ------------___--_--__________________________+
. ., ~;. : oa __--------__________________________+
; 45 \* I oa stands for "object addre~s" This word doe~ a compile time check for the class I
\* I descriptor of an in~tance data reference. At run time, this word provides the I
\* I current object's address as the base for referencing an instance data element. I
,~. \* + _ ______________________________________________+
~- 50 : object:
~: \ __----_____________________________________+
\* I This word is used to define an element within a class, where the element type is I
~:~ \* I actually an object of some other class. The MAKE or DMAKE of this class will I
r~i \* I automatically MAKE or DMAXæ the element object within this class's instance data. I
~', 55 \* I All methods of the object element's class can be applied against this element. I
~, \* I Example useage:
~,i \* I
;\* I <otherClass>: object: +otherClassObjElement \* I
60 \ + ---------------_______________________________+
~ .
: objects:
__________________________+
\* I This is like object: except it provides for the definition of an array of objects I
?! 65 \* I of the specified class. References must provide an array index value. I
: \ +___________--________________________________________________________________________+
~' `; -77-. , .
:`

2122~82 mion:
+____________________________________________________________________________________+
\* I union: begins the definition of a choice of different element types within a I
\* I class's instance data definitions. Union: is used in conjunction with the word I
5 \* I with: to define a set of choices in the form: I
* I
\* I <classnameX> union: <eltnamel>
\* I <classnameY> with: <eltname2>
\* I . I
10 \* I
\* I <classnameZ> with: <eltnameN>
\* I ;union * I
\* I Note: The elements of a union must be elements of other classes or subclasses.
\* I
\* I It i9 presumed that somewhere within the class instance data some element will I
\* I store the selector that indicates how the union has been initiaiized; i.e., which I
i \* I choice of the possible forms has been used. Methods that are to reference the I
\* I union will need this information. While it is possible to provide this information I
\~ I external to the class and passed as a parameter to its methods, it is much better I
\* I practice to include this information as part of the class itself.
------------___________________________+
: with:
\ + ------- -----__----_________________________________________+
\* I with: continues the definition of a choice of different element types within a I
\* I class's instance data definitions defined as a union:. I
\* I An example:
\* I <classnameX> union: <eltnamel>
30 \* I <classnameY> with: <eltname2>
\* I . I
,:\* I
.!\* I <classnameZ> with: <eltnameN>
\* I ;union 35 \* I
\* I Also see union: I
_----------___________________________+
: ;union 40 \ + -------------___----__________________________________+
\* I ;union completes the definition of a union: See union:
~. \ ___----_________________________+
,, '; : ubyte:
\ + -------------______-__________________________________+
\* I ubyte: is a primitive data element type to define unsigned byte elements. I
,i \ -------- ----------____--___________________________+
~.~
. : ubytes:
\ + ---- ----------__-----___________________________________+
\* I ubytes: is a primitive data type for defining an array of unsigned bytes. I
,. \ -- ___________________________+
~ : byte:
i 55 \ + ------___----__________________________________+
'3 \* I byte: is a primitive data element type for defining signed bytes. Nhen a byte: I
\* I element is fetched, it will be sign-extended onto the 32-bit parameter stack. It's I
\* I sign bit i9 bit7 (leftmost bit). I
___________________________+
~; , 60 ; : bytes:
_------ __________________+
\* I bytes: is a primitive data element type for defining an array of elements of type I
\* I byte:

,, ~.~
., `::
. .

212~82 ~hort:
+_________________________________________________________ __________________________+
\* I short: is a primitive data element type for defining signed 16-bit elements. I
- \* I When an element is fetched, it will be sign-extended onto the 32-bit parameter I
\* I stack. It's sign bit is bitl5 (leftmost bit). I
------------___________________________________+
: shorts:
_--_------____________________________+
\* I shorts: i9 a primitive data element type for defining an array of elements of type I
\* 1 short:
-------- _____--___________________________+
: ushort:
\ + -- - ----------_----_______________________________________+
\* I ushort: is a primitive data element type for defining unsigned 16-bit elements. I
------ __------________________________+
;
: ushorts:
\ + -------_-----________________________________________+
\* I ushorts: is a primitive data element type for defining an array of elements of i !- \* I type ushort:
----------_____--___________________________+
..
: ulong:
------------__------______________________+
~, \* I ulong: is a primitive data element type for defining unsigned 32-bit elements. I
\* + _ ________________________________________________________________________+
~ 30 : ulongs:
------------_____________ _____________+
\* I ulongs: is a primitive data element type for defining an array of elements of type I
', \* I ulong:
_____________________________+
r. 35 , : long:
----------___________________________+
\* I long: is a primitive data element type for defining signed 32-bit elements. I
\* I It's sign bit is bit31 (leftmost bit). I
\ + ------_-----______________________________________+
~, ~ : longs:
~J \ * + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ +

;~ \* I longs: is a primitive data element type for defining an array of elements of type I
.~ 45 \* I long:
,.~ \ -- ---- ________________________+
,.. .
~ : pointer:
___________________________+
~`~ 50 \* I pointer: is a primitive element data type that is equivalent to ulong: It is not a I
:~ \* I strongly typed element, but is provided to indicate the cell is expected to I
. \* I contain a 32-bit pointer. See alias: for a strongly typed object pointer. I
.. , \ __------______________________+
' 55 : pointers:
:~ \ + ----------------------_------------________________________________________________________+
\* I pointers: is a primitive data element type for defining an array of elements of I
\* I type pointer:
-- ____--_____________________+

: ?bname , \* +____________________________________________________________________________________.~
\* I This word expects a cfa on the stack and checks it to determine that it is a I
\* I binding-set name. The system error routine is executed if it is not a binding-set I
65 \* I cfa. I
----------______________________+

~-:

:;- ~
. ~
~ -79-~. .

2~ ~2~82 ~ ~ bname \* I Display the class name currently associated with a task's instance of a binding I
\* I name. The task's task control block address is expected on the stack. I
S \ + _ ___--______________________________________________________+
~ : .bname \~ +____________________________________________________________________________________+
\* I This displays the class name currently associated with the binding-set name for I
10 \* I the current task (the task executing this word). I
__ _______________+

Table 6 . .
;:
:;

', ;

, .., , .
;;~
, I

. . .
,i i , ,.
.

ii :
, 1 t!
~, 80- :
, . ..

, ~

:
2~ 22~8~
.

~*******************************************~************
COPYRIGHT(C) 1991-1993 AG COMMUNICATION SYSTEMS CORP. *
\ ****************************~****************************
only forth definitions 0 cload fmtos : fmtos ;
include c4th.files/c9th.mmgr ( FMTOS - USER VARIABLE DEFINITIONS ) base @ decimal : prev-to-me + ------------------------------__________________________________________________+
\* I This word is used by the "user" word to link a newly defined user variable into I
I\* I the uvar list.
\ + -------------____-__________________________________________+
( FMTOS - USER VARIA3LE DEFINITIONS ) : user +____________________________________________________________________________________+
\* I user variables are defined to have an instance in each task's tcb (task control I
\* I block). This word creates a header for each new user variable and links it to the I
\* I previously defined user variable. This linkage us used to support viewing user I
\* I variables with the .uvars and T.uvars words. User variables are assigned an offset I
\* I within the tcb. A user variable name, when executed, adds this offset to the I
\* I executing task's tcb address. I
_--------___________________________+
-: same-as :~\ +____________________________________________________________________________________+
\* I Usage: same-as <uvarname>
\* I user variables are assigned successively larger cell offsets as they are defined. I
\* I They are intended to provide an offset into any given task's task control block I
\* I (tcb). Some tasks may be defined which do not have need of an instance of I
\* I previously defined user variables beyond some limited early set. The same-as word I
!35 \* I allows a new user variable to be defined with the same offset as a previously j ~'\* I defined user variable, so the tcb won't have to be so large to accomodate offset I
\* I cells for user variables not used by the task. This should be used with some I
\* I caution. Use of this word resets the user offset to the offset of the specified I
\* I user variable. I

: next-user-cfa ( user-cfa -- next-user-cfa 1 0 ) 8 + @ ;
user >trace<
__ _________________________+
\* I >trace< is a user variable that is used as a trace control flag by FSML and any ; \* I other words for which the designer may want to provide tracing. Setting >trace<
~ \~ I false turns off tracing and setting it true turns it on. I
\

` 50 : forget --------------------___________________________+
;, \* I Usage: forget <wordname>
\* I This word "undefines" the specified word and all the words in the dictionary that I
\* I were defined after the specified word. This word also fixes up the user table I
\* I linkage to compensate for user variables that were forgotten in the process. I
\ + t :, ` 2122182 - -~MTOS - socket socket! fopen ) _~o hidden also domain definitions : socket ____--_______________________________+
~* I Usage: socket <socketname>
\* I Creates a new socket name and allocates a 20 byte buffer who3e address is returned I
\* I by executing the name. I
:~ \ +----__________________________________________________________________________________+
`::
: socket!
s. \ -------- _----------___________________________________+
\* I Usage: ( addr ) <socketname> socket!
~5 \* I Expects an address on the stack and moves 20 bytes from it to the address returned I
\* I by <socketname>
\ + ---------_______________________________________________+
:;~
j : fopen :~, \* +____________________________________________________________________________________+
\* I Usage: <mode> fopen <path>
`1 20 \* I This is an interactive word to open a file whose Unix path is specified. I
\* I mode = O ==> read \* I mode = 1 ==> write \* I mode = 2 ==> read/write :, \ + -- -- --------------_____________________________________+
r,; 25 ' only forth definitions also hidden ~, create fergitbuf ," forget " 48 allot 1, : (forget) \ + ---------__------___________________________________+
\* I Usage: ' <wordname> (forget) \* I The regular "forget" word is an interactive word. (forget) is to be used so I
~r'l \* I another word can execute a "forget" during execution. I
-- __--------______________________+

456 define-memQ 456memQ ( used for creating TCBs ) : (kill) ~: ----------------------______________________+
;.1 40 \* I This is an internal word expecting the tcb address of a task to be killed. Each I
\* I task is either executing, suspended, waiting in the active list, or waiting on a ~, \* I semaphore. If it is suspended it's tcb is not linked to any list. Otherwise, the I
~' \* I task is delinked from the list. Finally, the tcb is released to the memory I
' \* I manager.I
45 \ +-----------------____----__________________________________+

~Y

,~,~., ~. , . i, `'1 `:;
~;
~ -82-.
..

kill 2 1 2 2 18 2 \* I Every tasX TCB contains a uaer variable "recvy-proc" which contains a pointer to a I
\* I system default recovery routine "rcvy-rout". The default recovery routine handles I
\* I three cases: I
\* I 1. kill \* 1 2. break \* 1 3. timeout \* I The user may use the default choice for this procedure or design a specialized I
\* I word to handle the particular requirements of their application and then I
-\* I initialize their task's "recvy-proc" user variable to point to the specialized I
\* I recovery routine. I
\* I
\* I The word kill executes the "kill" case of the recovery routine. The default I
\* I routine discards the cause flag (established for more specialized user-defined I
\* I recovery routines), gets the TCB token from the top of the parameter stack and I
\* I adjusts pointers within that TCB such that the next time that task is executed, it I
\* I will release the memory used by its TCB, cease executing, and return control to I
\* I the scheduler. In effect, the task having that TCB is cancelled. I
~20 \ + --- ---------____--_________________________________________+
-: die +____________________________________________________________________________________+
\* I A task may execute this word to kill itself. I
\ + ---- __-----_________________________________+
: make-tcb -- ___ __________________________+
\* I This word makes a new task control block of a size that depends upon the supplied I
\* I parameters:
* I pfa[word] = pfa of the word to be executed as separate task * I rlen = rstack length - must be multiple of 4 bytes * I plen = pstack length - must be multiple of 4 bytes \* I ulen = user-table size - must be multiple of 4 bytes \* I mtype = memQ type for managing tcb buffer ----------___----______________________+
, ( FMTOS - semaphore ) 12 define-memQ 12memQ
: semaphore +____________________________________________________________________________________+
\* I Usage: semaphore <name>
\* I creates a semaphore with the name specified. A semaphore i~ a 3-cell object:
+ --------------------------+
\* I I flink I \
\* I +----------------+ > links to tcb's of tasks waiting on semaphore \* I I blink l /

+ ----------------------_--+
\* I I (#sig - #wait) I semaphore counter \* I +-------_-_______+
--___ +

!
: , 21~2~82 signal +____________________________________________________________________________________+
\* I This word expects a semaphore address on the stack and signals the semaphore. If I
\* I one or more tasks are waiting on the semaphore, the first task in the waiting I
\* I queue is activated -- its tcb is removed from the waiting queue and placed at the I
\* I head of the scheduler queue. If no tasks are waiting on the semaphore, the counter I
\* I associated with the semaphore is incremented, indicating the number of times the I
\* I semaphore has been signalled. I
+ ------------____________________________________________+

: wait ------ _------______________________________+
\~ I This word examines the status of the semaphore whose address is given on the I
\* I stack. If the semaphore is signalled, its counter is decremented and the task I
\* I which is performing the wait operation continues execution. If the semaphore is I
\* I not signalled, the tcb of the tasX is removed from the scheduler queue and placed I
\* I into a waiting queue associated with the semaphore. The task ceases execution and I
\* I control is passed to the scheduler. I
---- ____--______________________+

: ?waiting ( token -- u ) ( return number of tasks waiting ) ,: \ + ___________________________________________________________________________+
~ \* I This word returrs the number of tasks that are waiting on the semaphore. I
+ ____------____________________________________________________________________+

' : ?signalled ( tok -- u ) ( return number of times signalled) -------- ___----___________________________+
~ \* I This word returns the number of times the semaphore has been signalled -------- __--_--___________________________+
: 30 : sem-reset ( token -- ) ( reset a signalled semaphore ) ,: \ + _--__---- _______________________________________________+
\* I This word examines the status of the semaphore whose address has been provided on I
\* I the stack. If the semaphore is in the signalled state, it will be reset to the I
\* I idle state. If tasks are waiting on the semaphore, or if it is already in the idle I
i \* I state, its status will remain unchanged. I
.. \ +
., ( FMTOS - get-e put-e, ... ) : get-e ( 'pipé -- adr32 ) ( get emp~y buffer from pipe ) ---- ___----_________________________+
; \* I The word get-e obtains an "empty" buffer from the pipe identified by the address I
i \* I ptoken. It returns the address of the buffer on the stack. I
,, \ -- ---- ___----______________________+
.~ 45 : put-e ( 'buf 'pipe -- ) .~ \ -- ----------__--------___________________________+
:, \* I The word put-e returns an empty buffer whose address is given by addr to the pipe I
:l \* I identified by the address ptoken. I
~ 50 \ + ------------_-----________________________~___________________+
,' : get-f ( 'pipe -- adr32 ) ( get full buffer from pipe ) ___----______________________+
\* I The word get-f obtains a "full" buffer from the pipe identified by ptoken. The I
55 \* I address of the buffer is returned on the stack. I
------ ------_______________+

,.

:
;
:
''~

,' ~ .
;''~

.. .

'' , : : , :, ~ . :
: .
:: ::

2~2~82 `~ut-f ( adr32 'pipe -- ) t place full buf into pipe ) +____________________________________________________________________________________+
\* j The word put-f takes a full buffer whose address is given by addr and places it I
\* I into the pipe identified by ptoken. I
\ + -----------_____-_--_________________________________________+
; : xget ( adr32 'pipe -- adr32' ) ( xchg empty for full buf ) + ________________________________________________________+
:' \* I The word x-get exchanges an "empty" buffer whose addres3 is given by addr-e for a I
\* I "full" buffer whose address is given by addr-f. The "empty" buffer is returned to I
\* I the pipe identified by ptoken and the "full" buffer i.s obtained from that same I
\* I pipe. I
i. _______+
~ 15 : xput ( adr32 'pipe -- adr32' ) + ------------------_--________________________________________________________________+
~! \* I The word x-put exchanges a "full" buffer whose addres3 is given by addr-f with an I
;j \* I "empty" buffer whose addres3 i~ given by addr-e. The "full" buffer is obtained I
\* I from the pipe identified by ptoken and "empty" buffer is obtained from the same I
, 20 \* I pipe. I
,i, -- ______________________+
,~i : purge-ebufQ
-------- ____________________________+
';' 25 \* I Delink all objects on an empty buffer queue and return them to the memory manager. I
;~ \* I This word is used by the pipe "close" word. I
!`l \ +~~~~~~~~~~~~~~~~~~~~~~~~~------------------------------------------------___________+
;' : purge-Q
\ + ---------_______________________________________________+
Si \* I Delink all objects on a queue and return them to the memory manager. I
, \* I This word is used by the pipe "close" word. I
--------________________+
~ 35 : new-pipe ~ \ +-- --------------------________________________________________________________________________+
i \* I This is the creating word for pipes, normally used by the "open" word for pipes. I
'~i \* I A190, see pipe. I
" \* + __________________________________+
~ 40 !
'';.`
' ' '1'' i'`i .
~, '.i ~i .' ~

~,1 '`'~, ~, ' '' .
.
,, .

i~
.~

2~2~82 ?+_________________________________________________________________________________ __+
\* I The word pipe is used to define a type .~f pipe. It specifies the number of buffers I
; \* I to be used when the pipe is opened together with the type of the buffers to be I
\* I used. The buffer type should previously be defined using define-mem. Usage is a I
\* I follows: 10 60memQ pipe p-name \* I
\* I Each pipe instance has two semaphore structures and a pre-defined number of \* I buffers by which inter-task communiction can take place. If a task is waiting for I
\* I an input from a pipe, or must wait to send an output into a full pipe (all empty I
\* I buffers have been consumed), it's task control block (tcb) i~ linked into the I
\* I associated semaphore queue. When the semaphore is signalled due to arrival of an I
\* I appropriate buffer (either full or empty, depending upon which semaphore is being I
; \* I considered), the next queued task will be moved to the active scheduling queue to I
i 15 \* I process the event at the next activation opportunity. I
, \* I
3 \* I pipe structure \* I semaphore empty sending task tcb's ,/ \* I +________________+ +________________+ +________________+
!~20 \* I I Q-top *-1-->1 *-1-- - - -->I 1<--+
+ + + ----------------------------+ +________________+
,i\* I I Q-bot *-l----------------------------------------------------+
+ ----------------------------_+
* I I empty count I empty buffers 25 \ I +________________+ +________________+ +________________+
* I /l empty buffer Q l-->l *-l-- - - -->i + + + ------------------+ +________________+
i'\* I next / I
\* I cell \ semaphore full waiting task tcb's 30 \ I \ + - ---+ +----____---_____+ +________________+
* I \l Q-top *-l-->l *-l-- - - -->I l<--+
+ + --------+ +________________+
~~\* I I Q-bot *-l----------------------------------------------------+
:!\* l +-------- +
;,35 \* II full count I full buffers + + + ------------------+ +________________+
~ \* I I Q-top l-->l *-l-- - - -->I l<--+
+--------------------------------+ +--------------------------------+ +________________+
* I I Q-bot l----------------------------------------------------+
~i40 \* I +________________+
* I
----------__------___________________________+
'3 : open ,~ 45 \ + ----------------_------__________________________________________+
~l \* I Open an instance of a pipe. The ptype must be obtained by a previous definition of I
\* I a pipe type using the pipe word. Executing the associated <pipe name> returns the I
\* I ptype. Also, see pipe. I
\------------__--------_____________________________+

: close s~. \* + ________________________________,_______+
\* I Close an instance of a pipe associated with a token received when executing the I
\* I open word.
55 \ +--- -------_------____________________________+

., .~
:.~
~!

~, .

:

- : -, . : : : ,, - : -: :~ .

2122~ 82 3Zuspend_ - - ~~~~~ ~ ~ ~~ ~ ~~ ~ ~~~ ~~ ~+
\* I The word suspend causes the task whose TCB i3 given by token to cease execution. I
-\* I The task itself is left in a stable state, such that it can be resumed at any time I
\~ I in the future. I
-- ------------______________________________________+
. .
resume !~.Z \* +-------------------------___________________________________________________________+
~"10 \* I The word resume cancels the effect of a suspend operation on a task whose TCB is I
:i\* I identified by token. Most commonly this will enable the task to resume execution I
~\~ I unless additional suspend operations are in effect.
---- --------------_------______________________+
.,~15 : (sched) ----------__--------___________________________+
,l\* I This is an internal word used by schedule and [schedule]. It makes a tcb and hooks I
,3 \* I it into the scheduling queue. I
.. \ ---- ----------__--_----___________________________+

: schedule ( schedule following word ) ,;, \ ------------_------________________________+
\* I Usage: schedule <name>
\* I Schedules the specified word as a task. I
\ + -----------------------____---___________________________________+
i, : [schedule] ( schedule following word at execution time ) ! \* +---------___________________________________________________________________________+
\* I Usage: Within : definition... [schedule] <name> .... ;
-; 30 \* I Schedules the specified word as a task at execution time. I
+ -- ___________________________________________________________+
Z~l ~; : dummy ____--______________________+
\* I This is a dummy task to ensure there is always at least one tcb in the scheduling I
\* I queue. I
~,1 \* +____________________________________________________________________________________+
r,ll : tcom \ + _------------_----_------________________________________+
I \* I This is the internal timer control word used by the "timer" word. Also see tmgr Z
:i : timer \ + ----- -------____---____________________________+
\* I This word defines a timer instance for the task which executes the timer word. ul I
~,j \* I and u2 are parameters which the user may specify to return particular information I
,i~ \* I or identify the timing event when several different timers may be simultaneously I
'1 \* I running. I
\* I
'i \* I The tasks recovery procedure timer entry will be executed if the timeout occurs, \* I and the recovery procedure can be designed to interpret the returned parameters ,, \* I (ul ~ u2) and take whatever action the application requires. Also see tmgr ,7j \* + _ _ ________________________________________________________________________+
~l 55 ~:Z

,,.
`Zl ~ .~
:`.
.~
: ' . ..
:~`
.;, 'i `!
., :`,`

.. ` - . ` - . . ' . . . - .- . . ~ , . . -., -., . . ~ "- .

2122~8~
-ancel-timer ( 'timeblk -- ) ( halt a timer ) \* I When a specific timer instance has been created, using the timer word, a timer I
\* I token (ttoken) is returned. Normally, this timer will run and upon timeout cause I
\* I the timer entry of the associated task's recovery procedure to be executed. The I
\* I cancel-timer word allows the timer to be cancelled prior to timing out, thus \* I avoiding the timeout event. Also see tmgr ,j \ ------ ----------_______________________________+
: seconds 10 * ;
: minutes 600 * ;
: awaken dup 16 + @ resume mput ;
( FMTOS - timer manager ) : delay \ +
3 \* I This will suspend the task executing the delay for a period of u tenths of a I
i3 \* I second (ticks), then awaken the task. I
i. \ + ------------__----------__________________________________+
, 20 semaphore tsem ( timer semaphore ) : tmgr ( timer manager task ) ---- ----------____-- ___________________________+
\* I This is the timer manager code that runs in a continuous loop as a control task to I
25 \* I support fmtos timing functions. The timer manager waits on the tsem semaphore I
' \* I which is signalled once for each tick by the ticks word. I
., \* I
S \* I For each tick, the timer manager is unblocked and allowed to execute. Each time it I
\* ¦ executes, it steps to the next timing list in a queue of 64 separate lists. It I
30 \* I traverses each entry that happens to be linked into the particular timing list, I
~i \* I checking the entry's timeout value against the current wall-time. If it is equal I
i \* I to the current wall time, the entry is removed from the timer list and its I
: \* I supplied execution address is executed. The execution address which may be I
~ \* I specified as any cfa when the timer is started, or defaults to the task's recovery I
q 35 \* I routine. I
.j \* I
\* I After a list has been traversed all its entries containing the current wall-time I
~! \* I will have been removed, and thé tmgr then increment~ the global wall-timer I
\* I counter. I
\ + - --------------_____-___________________________+
: ticks ( n -- ) ------ --------------__------______________________+
~ \* I Increments the wall time variable by #ticks. Also see tmgr ,- 45 \ + ----- -------_------____________________________+
â ( FMTOS - recovery routine ) : (breaX) drop ; ( dummy break routine ) ~' : break 50 \ + --- -------___________________________________+
\* I This is a debugging aid which can temporarily be compiled into the definition of a I
\* I task in any logic path the user wishes to analyze interactively. When a task is I
\* I executing and encounters a break, it is rearranged in the scheduling queue in such I
.;' \* I a way as to become the terminal task. The user may then interact with the task, I
55 \* I dump memory, view and/or change stack contents for the task, spawn other tasks I
\* I interactively etc. A break level indicator LVL[n~ is displayed since more than a I
\* I single level of break is supported.
-------------- ___ _______________+

.'.:
:

`:

`:- : :: : :: ~ .

2122~2 ^ecvy-rout +____________________________________________________________________________________+
\* I This is the default recovery routine, called with the appropriate token depending I
\* I upon what routine calls it. I

decimal user OUT
----------___----________________________________+
\* I OUT is a user variable whose contents indicate the number of output characters 1 \* I have been emitted since the previous carriage return. This can be used by words I
\* I that are required to produce formatted output text with "smart" indentation I
\* I control. I
-------- ____--________________________+

: out!
___----______________________+
\* I i/o CELL+ is a global variable that contains a pointer to the primitive routine to I
\* I be used for output to the screen. Normally, this would be the nucleus primitive I
\* I etype. To support the availability of the current output column in the user I
\* I variable OUT, out! increments OUT when strings are typed, and zeros OUT when a I
\* I carriage return is emitted. After this, out! executes etype. The address of out! I
\* I is loaded into i/o CELL+ to enable this feature. I
__--_--______________________+

Table 7 :

;

, 2~22~82 .. .
~********************************************************
~ COPYRIGHT(C) 1991-1993 AG COM' NICATION SYSTEMS CORP. *
\ *********************************************************
0 cload fsml 5 only forth definitions ~ create task-fsml '~ vocabulary fsml also fsml definitlons ( FSML CODE - variable definitions ) f 10 hex :^ 40 CELLS constant Rsize 20 CELLS constant Psize 64 CE1LS constant Usize ~' 32 ( hex ) constant #STATES
15 2 20memQ pipe input-pipe Rsize Psize Usize + + define-memQ mach-memQ
,.
~:~ user curr-state ------ -- ___----________________________+
.'' 20 \* I Each instance of a finite state machine runs as a separate task with a task I
. \* I control block (tcb) containing task-specific variables, called "user variables". I
:~j \* I
. \* I curr-state contains the pointer into the state-input table (SIT) for the current I
'i; \* I state of the machine. I
\ + -- --------------______-_______________________________________+
~; user in-save ~:f \ +____________________________________________________________________________________+
f' \* I Each instance of a finite state machine runs as a separate task with a task I
~' 30 \* I control block (tcb) containing task-specific variables, called "user variables". I
... , \* I
\* I in-save contains the last input token sent to the machine. I
$ -- --------------------_____________+
~..
';,~ 35 user prev-state -------- --------------____--________________________+
"f \* I Each instance of a finite state machine runs as a separate task with a task I
-:, \* I control block (tcb) containing task-specific variables, called "user variables". I
\* l \* I prev-state contains a pointer to the previous state for this machine. I
~,, \ ----_---- ___________________________+
`~ user my-pipe :. \ + ----------------_----------------___________________________________________________________+
:i 45 \* I Each instance of a finite state machine runs as a separate task with a task I
\* I control block (tcb) containing task-specific variables, called "user variables". I
.~j \* I
~:; \* I my-pipe contains a pointer to this machine's input pipe. I
.4 \ + -- -- -- -- -- -- -- -- -- -- _ _ _ _ _ _ -- _ -- -- _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ +
~ 50 user 'process i~ \ +____________________________________________________________________________________+
\* I Each instance of a finite state machine runs as a separate task with a task I
~: \* I control block (tcb) containing task-specific variables, called "user variables". I
;if~' \ *
rj 55 \* I 'process is automatically updated when a message is sent to this machine. The fsml I
\* I message header structure contains the value of 'process supplied by the sender. It I
\* I typically contains a pointer to a message body containing information elements I
'~ \* I required by the application. I
+ _______--___________________________________+
~ 60 : (in-srch) __--_--______________________+
~ \* I Ihis is an internal fsml word that searches a linked list of defined fsml inputs `~ \* I and returns a true flag and a pointer to the pfa of the input if it is defined. If I
\* I the ivalue supplied does not correspond to a previously defined fsml input, only a I
65 \* I false flag if returned. I
----___________+
. .
',~ .
::.

.:
::~
:;.
:

. . :

2122~2 :ype.r +____________________________________________________________________________________+
\* I This is a primitive to type a string right adjusted within a specified width. If I
\* I the string is longer than the specified width, it will be truncated on output : id.r . \ + ---- -- ------____ _______________________________+
i~ \* I This is a primitive that types the identifier as~ociated with a cfa (a word name) I
\* I right-adjusted within a specified width. I
~, \ -------- ----------______ ________________________+
: (.~t) -------- ----------_____ ____________________+
\* I This is an internal primitive used to type a Itate name associated with a State I
; \* I Input Table address ~ 'SIT ). I
----------__ ___________________________+
tate \ + ------ --_____ ___ ____________________________+
\* I Thi~ word will type the state name of the current state of the current machine. I
---------- ------___ __ ____________________+
` : .mach \ + ------ _______ __________________________+
\* I This word type~ out the name of the fsm whose tcb is supplied on the parameter I
\* I stack. I
. \ + -------- __ __________________________+
, 30 : .in __ _ ____________+
\* I Supplied an input value (Token), this word types out its name, right-adjusted in a I
\* I width of 18 characters. Longer name~ are truncated. I
\* +____________________________________________________________________________________+

. : .tim~
---- --------___-- ___________________________+
! \* I This word displays the number of ticks in the wall-time counter. I
:'! \* +_____________________________________________________________________------__-__----+
,, 40 :i : .intrace ---- --------___ _ _______________________+
\* I This is an fsml trace support word. It outputs trace data associated with an input I
\* I event. I
45 \ + ---_____________________________________+
!
, ~
.~, ~t .,t ., ' .
~"' ~, ~' ';' .~ .
~ .

.~ --9 1--. .

2122~82 '-l ose-my-p___ _ ____ _ __________ ___ __ _ __ __ ___ ___ _ ______ ______ ___ _ _ __ __ _ ___ _ _ __ __ _ __ ___ _ _ _+
\* I This word closes a machine's input pipe and cleans up any attached buffers. This I
\* I will be used when a machine executes its recovery routine, such as when a machine I
\* I is being "killed". I
---- ___--______________________________+
~ : mrcvy-rout + ___ _________________________________________________________+
r 10 \* I This is the default recovery routine for fsms. It is executed when a machine is I
\* I being killed, hits a break, or has a timeout. I
\* I The timeout case supports an interface with the timer manager which essentially 1 \* I sends a message of the same form as fsml mes~age headers to the input pipe of the I
\* I machine that started the timer. This is set up by the start-timer word. I
15 \ + ---- -------____--_________________________________________+
¢
'j : (start-state) -- ----------_ ----______________________________+
\* I This is an internal word that initialized the state of a machine. I
\ + ------------____---__________________________________+
: (m-sched) t _ _ _ -- _ _ _ _ _ _ _ _ _ _ _ _ _ _ +
\* I This is the internal word that schedules a new instance of a fsm. It allocates a I
25 \* I special tcb for fsms and schedules the task for the new machine. I
t \ -- -- -- -- -- -- _ _ _ -- -- _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ +
ti 3 : doit +------------------------------------------------------------------------------------------------------------_--------_________________________+
\* I This is an internal primitive, used by (run-mach) to transfer control to a code I
\* I thread. I
~, \-- ----------____________________+
., i : (run-mach) 35 \ +------------____________________________________________+
\* I This is an internal word that checks whether an fsm instance has an input, and if I
\* I so, it executes the appropriate thread of code for the current state of the I
i \* I machine. I
-- ___________________________+
~ 40 ;i : .dest ~' \* I This is an fsml trace support word that print~ the 'tcb and name of a machine. I
q5 --_-______+
: .outtrace s. \ +------ ----------------___--___--______________________________________________________________+
i \* I This is an fsml trace supporting word that displays a line of trace output in I
:`~ \* I conjunction with an fsm output to another machine.
~,, SO\ + -------- ----------____-- __________________________________+
j : ton ----------_________________________+
~ \* I This is a control word that turns on fsml tracing. It will apply to the current I
\* I machine and any "child" fsms spauned by the current machine. I
-- --------__ _________________________+
.

,:

;i ;t `
\ i .,, !, ~ 92 ;`'~
, . ~
~: .

:off +____________________________________________________________________________________+
\* I This is a control word that turns off fsml tracing in the current machine. I
+____________________________________________________________________________________+
~ 5 - : .trace X \ + _______________________________________________________________________________+
~, \* I This is an internal word used for fsml tracing to display trace output headers. I
~ \ ------------_----------_______________________ _____+

~' : pass-on , \* + _______________________________________+
~, \* I This is an internal fsml word that passes an input to a machine.
__---- ________________________+

1 : input-match ----------------------___________________________+
\* I This is an internal fsml word that attempts to match an input value in the SIT I
\* I (State Input Table) and return the address of the appropriate action table. I
~, 20 \ + --- -----------______--_______________________________+
: proce~s-input ~. \ ----------____----___________________________+
\* I Thi9 is an internal fsml word that vectors an input to the appropriate thread for I
25 \* I an fsm ~tate. I
~1 \ ------------_------.___________________________+
~il ~1 : reset-fsml ------ ______________________+
~ 30 \* I This is an internal fsml word that zaps the fsml-state variable ----------------------___________________________+
~ : .err ---- ----------________________________________+
\* I This displays FSML errors encountered during compiling : ?st=O
+ ------------------__________________________________________________________________________+

Pl 40 \* I This is an internal fsml word that generates an error message if executed while I
; \* I not in interpreter mode. I
,:~ \ + ---- --------------_______--_______________________________________________+
: ?st=l \ + - -------___-_--_________________________________+
\* I This is an internal fsml word that generates an error message if executed while I
\* I not in compiling mode. I
.. ,. \ -- -- -- -- -- -- -- _ -- -- -- _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ +
^:i 50 : ?cschk ~, \ -- ----------___________________________+
`~, \* I This i~ an internal f9ml word that generates an error message if the supplied I
~ \* I state is not equal to the state value in fsml-state.
------ ----------___________________________+
S S
.warn ~? \* +--___------_________________________________________________________________________+
-- \* I This is an internal fsml word for issuing a warning message during fsml I
.Y, \* I compilation. I

`i`;
`,il :
.,;, :.
. . .
~i -93-2122~82 ~SML CODE - sit table ) _riable state-input-tbl-ba3e variable state-input-tbl-ptr OdO ( 208 ) state-input-tbl-base !

\ THIS DEPENDS ON SCREENS!
\ THIS BUILDS STATE INPUT TABLE IN B~OCK
~ VIRTUAL MEMORY, THEN TRANSFERS IT TO THE DICTIONARY
: SIT, ! \* +____________________________________________________________________________________+
\* I This store3 a State Input Table value in a buffer that will eventually be copied I
j \* I into the dictionary.
------------_ ----_____________________________+

: SIT>dict ---------- ____________________+
\* I This is an internal fsml word that transfers a State Input Table that has been I
\* I initially compiled in a disk buffer back into the dictionary. This is done so that I
\* I action routines that are part of an fsml definition are not interspersed with the I
\* I SIT, making its address offsets invalid. I
___________________________+
i : 0>SIT
\ + ------ __________________________________________+
\* I This is an internal fsml word that initializes the pointer to the State Input I
\* I Table. I
----------______________________+
, 30 : SIT--+ ______--_----_____________________________________ _____________________+
\* I This is an internal fsml word that decrements the pointer to the State Input I
\* I Table. I
______ ___ ______________+

: 'SIT
_____ ________+
¦ \* I This is a word that returns a pointer to the current State Input Table. I
-- --_________________________________+

: machine ----------___ _ ______________________+
\* I Usage: machine <machine-type-name>
\* I This is the defining word for a new finite state machine type. I
\ + ----- ____---___________________________________+
: [m-schedule]
+ ------------ ------------------______________ _____________________________________+
\* I Usage: [m-schedule] <machine-type-name name>
\* I This is a word that may be compiled into another word, such as a : definition, I
\* I which when executed, will schedule an instance of a machine of the type specified. I
------ -- ___________________________+
create end-states ( u3ed to terminate states ) \ + - ------_________________________________________+
\* I Terminates state predefinition sequence. See states ------------_______________ _ _________~

:`
., .

, 212~82 `-ate st-lnk 0 , +____________________________________________________________________________________+
\* I This is the head of an internal fsml state link-list, used to check and administer I
\* I state names. I
\ + --- - ---------_______________________________________________+
create dpth 0 , ------------___________________________________+
\* I This is an internal fsml variable used in the stack word for checking for abnormal I
\* I stack depth during fsml execution. I
+ ------------------_--------_____________________________________+
; : (states) ,: \* +____________________________________________________________________________________+
\* I This is an internal word, used by the "states" word to predefine the states of an I
\* I fsm. I
________________________________+
' : states \ + ------ --_------__________________________________________+
~; \* I Within a machine type definition, the code between machine and states constitutes I
~ \* I initialization code that will be executed when an instance of the specified I
!~ \* I machine type is scheduled. Between states and end-states is a list of states that I
~ \* I are to be used by the machine type being compiled. Example:
i~ 25 \* I
5~ \* I machine <machine-type-name>
\* I
\* I . > fsm prolog :,\* I
-~30 \* I
\* I states ~:\* I <state-namel>
~* I <state-name2>
\* I . \ State ~35 \* I / predefinition list ,`.' \* I . I
:;\* I
-\* I <state-nameN>
\* I end-states '40 \* I
,, \ _----_----__________________________+
~ ( FSMl CODE - error help display routines ) '- decimal ; 45 : ERRSCN
+ ------------ ------_------------______________________________________+
.' \* I FSML error messages are located on cforth screens, taking advantage of the screen I
\* I virtual storage access mechanism. Each error message is simply encoded as text in I
\* I a forth screen. The ERRSCN word is the first word on each screen, causing the text I
\* I to be printed out when acce3sing the screen via the "load" word. I
:, \* +____________________________________________________________________________________+

~ : -more-----------_______________________+
\* I This is an extension of the ERRSCN word. When an FSML error message requires more I
~l \* I than a single screen, the preceeding ~creen(s) prompts to hit a non-RETURN key. I
.~ \* I this word will then list the next screen.
--------------------------______________________+

~ 1 ~, .,.
. ~

, "~,~
.
., .,.

2~22182 ?SML CODE - input input! ) creata input# 1 , ( auto-defined input value ) -1 constant or-else O , Occ8e , ~i 5 ' or-else >body in-lnk ! ( linked list of inputs ) r next-input _---- _____________________________+
\* I The FSML "input" word assigns input value_ to input definitions. This word I
\* I generates the automatically defined input values. This word is an internal FSML I
; \* I word not normally accessed directly by the programmer writing FSML code. I
~ \ ___------__________________________+
: input!
' 15 \ + ----------------_______________________________________+
! \* I Usage: <value> input <input-name>
\* I This word is like the "input" word, except instead of automatically assigning an I
\* I input value, input! accepts a user-defined value for the particular input. Before I
\* I beginning definition of inputs with automatically assigned values, The user can I
-j 20 \* I preset the input# variable to some value out of the range of the manually assigned I
i~1 \* I inputs to allow concurrent non-conflicting use of the "input" automatic definition I
I \* I of values and the "input!" manually assigned values. I
p! \* +____________________________________________________________________________________+
~`, i1 25 : input :I \ +-- -- -- ____________________________________________________________________________+
.j \* I Usage: input <input-name>
~- \* I Thiq will define a new FSML input and asqign the next available automatically !
r. \* I a_signed value to it, using the input# variable to select the next value. input# I
1 30 \* I is then incremented. I
-------- ________________________+
; : state :, \ + ______--_______________________________________________________________________+
; 35 \* I Usage: state <state-name>
\* I This word is used within the body of an FSM definition to specify the state I
\* I behavior of the named state. It is followed by a liqt of inputs accepted by the I
\~ I qtate with correqponding next-states and output action code. I
-- ____--______________________+
" 40 : ?valid-in __------________________________+
\* I This is a word to check that an input value is associated with a valid FSML input I
` \* I definition. This is an internal FSML word. I
; 45 \ + ----- -------_------____________________________+
.. : ~
+____________________________________________________________________________________+
;` \* I Usage: <input> <next-state> ~ <output action code> ~ I
\* I This word specifies the beginning of the output action for a state-input pair.
., \ ---- ------------___________________________+
~ (stk-chk) ~,j \ +____________________________________________________________________________________+
\* I This is an internal FSML word that checks for a valid parameter stack depth during I
\* I execution of an FSM. A warning is displayed if the stack depth is invalid in the * I context of the machine. I
------ -- ----------________________________+

~;

~' .
~, ~
,., , .
. .

sj ,~
,,~
r:

2~22~2 ,...
+ +
\* I Usage: <input> <next-state> { <output action code> ~ l \* I This word terminates the definition of the output action code for a state-input I
5 \* I pair. I
-- ____--________________________________+

: (inner) \ + ------ ----------------__------_______________________________________________+
\* I This is an internal FSML word used for compilation of a machine. I
-- -- __----____________________________+
: start-state ( <state-name> ) \ + -- - -------__---_____-________________________________+
\* I This word terminates the definition of a machine type and specifies the starting I
\* I state initialization for instances of the machine type. I
-- ------------------___----_________________________+
: create-timer ------ --------------------________________________________+
\* I Usage: <input-name> <#ticks> create-timer <timer-name>
\* I The create-timer word is used to create a timer "type", characterized by the input I
\* I value it will return and by the number of ticks which defines its period. Each I
i 25 \* I tick corresponds to .1 second, or can be simulated using the "ticks" word. When \* I executed, the <timer-name> word returns an address on the paramter stack which can I
\* I be used later in conjunction with the start-timer word to establish a particular I
\* I instance of the timer and with the reset-timer word to reset an instance of the I
\* I timer. I
\* I
\* I <timer-name> returns a pointer to the timer type structure:
\* I
+--------------------------___+
* I +----->1 #tick~ I I
35 \ I +________________+
\* I I input-value +----------------________+
\* I
\* +____________________________________________________________________________________+

: 'pipe + ____ --_______________________________________+
\* I Each FSML machine has a user variable containing the pointer to its input pipe. I
J \* I This word accepts the tcb address of a machine 13 task and retrieves that machine's I
~ 45 \* I pipe address. This i~ normally used internal to FSM1.
~, \ ------ _______________________+
`I :
;l : >chan __________________________+
\* I This word feeds an input to the machine instance specified by the 'tcb on top the I
\* I stack. I
---- _________________________+

.

"
~: j ':' .~, .
2122~ 8~
~~channel ------------~~~~+
\* I Usage: I
\* I user <uvar-name> \ defines a user variable to use wi~h channel ` 5 \* I <uvar-name> clear \ initialize the user variable \* I <uvar-name> channel <access-name> \ defines a channel access name :1\* I <input-name> <access-name> \ sends input to machine attached to channel \* I A channel may be used to establish a 1-1 or N-1 communication binding between I
\* I different machine~. The "channel" word is u~ed to define an access name for I
\* 1 sending inputs to a machine from other machines which have attached to that I
\* I channel using the ch-attach word. I
\* I
:. \ +____________________________________________________________________________________+
\* I FSML CHANNEL STRUCTURE
i15 \* I The FSML channel structure is built upon the FMTOS communication pipe mechanism. 1 ;\* I "pipe" is a FMTOS data type which may be used to create any number of instances of I
\* I communication pipes. Each pipe instance has two semaphore structures and a I
\* I pre-defined number of buffers by which inter-task communiction can take place. If I
\* I a task is waiting for an input from a pipe, or must wait to send an output into a I
\* I full pipe (all empty buffers have been consumed), it's task control block (tcb) is 1 \* I linked into the associated ~emaphore queue. When the semaphore is signalled due to I
\* I arrival of an appropriate buffer (either full or empty, depending upon which I
\* 1 semaphore is being considered), the next queued task will be moved to the active I
~- \* 1 scheduling queue to process the event at the next activation opportunity. I
25 \* I
\* I user table * I ' CH->X >body ( pfa )-> offset + self -------+ +----------------+
. \* I I I . I
:: \ I I +________________+
30 \* I +-->l ptr to pipe X l---+
+________________+
:,\* I
.\* I
\* I +_______________________________________________________________________+
\* I I semaphore empty sending task tcb's ~ \* I I +________________+ +________________+ +________________+
~ \* I +---->l Q-top *- 1-->1 *- 1-- - - -->I l <--+
\* I +______ __ + +________________+ +________________+
\* I I Q-bot *-l----------------------------------------------------+
40 \ I +--______________+
\* I I empty count I empty buffers + + + ------ ----+ +________________+
~\* I +---l empty buffer Q l-->l *-l-- - - -->I
.;,\ I I +________________+ +________________+ +________________+
n45 \* I nextl ;l- \* I celll semaphore full waiting task tcb's \* I I +________________+ +________________+ +________________+
i~\* I +-->l Q-tOp *-l-->l *-l-- - - -->I l<--+
;\* I +________________+ +________________+ +________________+
:l50 \* I I Q-bot *-l----------------------------------------------------+
~\* I +________________+
\* I I full count I full buffers :,\ I +________________+ +________________+ +________________+
;\* I I Q-top l-->l *-l-- - - -->I l<--+
55 \ I + ---+ +-----------_____+ +________________+
~:~\* I I Q-bot l----------------------------------------------------+
, \ I +----------------------_____+
~'\* l +________________________________ ___________________________________________________+

: ali2s :~ \* +____________________________________________________________________________________+
\* I Usage: <machine type name> m-schedule alias <alias-name>
\* I This word can be used to specify a symbolic name by which to reference an instance 1 65 \* I of an FSML machine type. I
, -- ----------_________________+
'~:

.~

:`
~` -98-"

.
,. . :

- m- 9 chedule +____________________________________________________________________________________+
\* I Usage: ~machine type name> m-schedule ~* I m-schedule is the interactive word for scheduling an instance of an FSML machine I
5 \* I type. I
---- ____--________________________________+
also hidden : ch-attach 10 \ + -- --------------__--------_________________________________________+
\* I The channel word is used to define 1-1 and N-l communication bindings between I
\* I FSMs. It is associated with a user variable, so any machines defined after a I
\* I channel's user variable has been defined will create a corresponding user variable I
\* I instance for each machine instance. Before a channel can be used for communication I
\* I between machine x and machine y, a ch-attach operation must be executed to set up I
\* I the linkage. I
\* I EXAMPLE:
\* I Assume previous definitions:
\* I machine xyz ( machine type definition ) \* I input inl t input definition * I
\* I The following definitions to be compiled:
\* I user uch->xyz ( user variable for channel ~ I
\* I uch->xyz channel ch->xyz ( define channel access word ) 25 \* I uch-xyz clear ( initialize channel uvar I\~ I [m-schedule] xyz ( -- 'tcb ) ( create instance of xyz ) ¦\* I uch->xyz ch-attach ( binds ch->xyz to instance of xyz \* l \* I During execution:
30 \* I inl ch->xyz ( serd inl to instance of xyz attached to ch->xyz ) ---- ----------_____ _ ______________ +

,j ( ij :

,j . !

f _99_ .

~ ~
-~ ~lex + _____________________________________________________________________________+
\* I A plex is similar to a channel except the plex supports 1-N and N-M communication I
\* I bindings between fsms. Instead of defining a name of a single communication I
\* I channel, plex defines the name of a set of numeric values wherein each member of I
j \* I the set corresponds to a communication port instance. Like a channel, a plex I
,r \* I requires an associated user variable definition. I
\* ¦ EXAMPLE: I
\* I Assume previous definitions:
\* I machine xyz ( machine type definition ) \* I input inl ( input definition \* I
\* I The following definitions to be compiled: I
\* I user ulx->xyz ~ user variable for plex 15 \* I ulx->xyz plex pl->xyz ( define plex access word ) \* I ulx-xyz clear ( initialize plex uvar * I [m-schedule] xyz ( -- 'tcb ) ( create instance of xyz ) * 1 5 swap ulx->xyz p-attach ( associate index=5 with instance of ulx->xyz and ) \* I ( linked to instance of xyz identified by 'tcb \* I
\~ I During execution:
\* I inl 5 pl->xyz ( send inl to instance of xyz attached to pl->xyz[5]) 1 ~ \ ---- --------------------_------____________________________+
: p-attach \* + ___________________________________+
; \* I Associates a selector index with an instance of an FSM
, \* I EXAMPLE:
\* I Assume previous definitions:
\* I machine xyz ( machine type definition ) \* I input inl ( input definition :: \* I
` \* I The following definitions to be compiled:
* I user ulx->xyz ( user variable for plex 35 \~ I ulx->xyz plex pl->xyz ( define plex access word ) ~\* I ulx-xyz clear ( initialize plex uvar i'\* I [m-schedule] xyz ( -- 'tcb ) ( create instance of xyz ) .1\* 1 5 swap ulx->xyz p-attach ( associate index=5 with instance of ulx->xyz and ) \* I ( linked to instance of xyz identified by 'tcb ~!40 I During execution:
\* I inl 5 pl->8yz ( send inl to instance of xyz attached to pl->xyz[5]) 1 j:j \* +_______________________________________________________________+
~i 45 :~1 : p-detach ~i \*------__________________________+
! \* I Removes the communication port indicated by the index from the plex associated I
\~ I with the specified user variable. I
~i 50 \* I EXAMPLE:
\* 1 5 ulx->xyz p-detach ( see p-attach ) ----------------______________________+

1, : clear \ + ----- ----------_-----______________________________________+
\* I Initializes the user variable associated with a plex or channel.
\* I EXAMPLE:
~' \* I ulx->xyz clear ( see channel ch-attach plex p-attach ) -- ------------------_______________________+
1 ~ 60 ,, y .. ~, .
. .

," - 1 0 0-:` .
`:

~ ;tart-timer +____________________________________________________________________________________+
\* I The start-timer word creates an instance of a timer type whose address is passed I
\* I on the parameter stack. This address points to a cell containing the #ticks for I
- 5 \* I the timer, and the following cell contains the input token associated with this I
\* I timer. The start-timer word passes ( ['process] input #ticks ) to the fmtos timer I
i \* I function which adds the currently executing task's tcb to the stack and then I
\* I executes the fmtos tcom word. The tcom word allocates a timer buffer which has a I
\* I compatible format with fsml message headers, stores the supplied parameters in the I
\* I block and links it into the timer manager's timer queue related to the difference I
' \* I between the current wall-time and the #ticks supplied as the timeout interval. The I
\* I timer manager runs as a continuous looping task which waits on the tsem semaphore. I
- \* I Each tick signals the semaphore, and the tmgr processes one of it's 64 timing I
\* I lists. See the tmgr word for more detail. I
\*
~ \* I When an fsml timer expires, the tmgr essentially sends the related message token I
; \* I to the machine whose task timed out, restoring the value of 'process to the value I
~ \* I it had when the start-timer word was executed. I
r~ \ +~~~~~~~~~~~~~~~~~~~~~~~~--~~---------------------------_----________________________+
'' 20 ~ : read-timer :: \ + ------------------------___--____________________________________________+
;; \* I This word returns the number of ticks remaining on the specified timer. I
i,. \ + _____----______________________________________________________+

` : stop-timer \* + _ ______________________________________________________________+
; \* I This word cancels the specified timer without executing the function that would I
~' \* I have been executed if the timer had timed out. I
\ + - -- ------------_----____-____________________________+
:, .
: reset-tlmer -------- _________________________+
~ \* I This word resets the specified timer to its original timeout interval, essentially I
i,~. 35 \* I starting the timer over again. I
~;,I \ + ---------- ------------------------___------____________________________________+
. ..
s~ : >>>
;:. \ + ---- ----------_----------__------___________________________________+
:j 40 \* I There is a global pointer, curr-fsm which defines a "current machine". >>> sends I
"` \* I an input to the machine whose 'tcb is stored in curr-fsm. I
;~ \ ---- --------_ ________________+
i'~l : select \ + --- ------ ----____ _ ___________________________+
\* I This is an interactive word allowing the user to select a particular fsm to become I

~, \* I the current fsm (storing its 'tcb in curr-fsm). The fsm to be selected can be I
X~' \* I referenced either by its alias name or by its 'tcb. I
~, \* I EXAMPLES:
:s; 50 \* I select myfsm \* I select 105432 \* +-----------------------------------------------___--___________________________ ____+
-'I
.':, : mkill 55 \ + -------____--___________________________________+
.' \* I Kill the current fsm ;. --------______+
;. ~

.~ .
~ . .
.j '`~', , .
i :~;

::
,,~ .

212~ 82 'dq-setup) ( svar-offs -- ) \ save offset of state var \~ I This is an internal word for setting up a data query ( dq ) function for an fsml I
\* I state. I
\ + ----- _____-____________________________________+
: (dq-clnup) ------ ____________________________+
\~ I This is an internal word for ministering the needs of a data query ( dq ) I
10 \* I function. I
----------___________________________+
: tokenof -- -- ________________________________+
\* I Usage: tokenof <alias-name>
\* I This i9 an interactive word to retrieve the 'tcb of an fsm instance specified by I
\* I an alias name. I
-- _--------___________________________+
: dq:
--------__------_________________________+
\* I The dq functions provides a way to make a data query before processing the input I
\* I token sent to an fsm instance. For example, sometimes the input token may be a I
\* I general message input, but the functional input to the machine is stored within I
\* I the message. The dq function allows the message to be pre-analy~ed to substitute I
\* I the message parameter as the input before allowing the machine to process lt. Each I
\* I state of an fsm may have its own dq function, and if used, must preceed the first I
\* I input listed for the state. The dq: word is similar to the : word, except dq I
\* I functions don't have a header (i.e., no name). I
\* I Usage:
\* I dq: <any code here> dq;
\* I Also see mapto . I
__--_--_______________________+
: dq;
----------_______________________+
\* I This is to terminate a dq function. It is similar to ; . Also see dq:
----------_________________________+
~I
~ 40 : mapto ___----_________________________+
\* I The mapto word is used within a dq: function to substitute a different input token I
~-' \* I for the one originally received in the state. I
j, \ -- --------_--------____________________________+
; 45 ~l : (stateval) \* + ______________________________________________________+
' \* I Thi3 is an internal fsml word to convert the cfa of a state to its "value". I
,.~ \ ------ _________________________+
~;50 I : valueof + ______--_________________________________________+
\~ I Usage: valueof <state-name>
-, \* I This returns the value associated with each fsml state. I
SS \ + ------ ---- ------------___________ _________________+

:

:

,- : .

2~2~8~
~smlstate!
:~ + _ _ ______________________________________________________+
\* I This word updates an fsm instance state to the specified value. This is normally I
i \* I used as an internal fsml word. I
;~5 \ + ---- ----------______-__________________________________________+
: .synctrace ___--_________________+
-j\* I This is an internal word that supports the fsml trace capabilities. See ton and I
~10 ~* I toff . I
~,\ -- ___------___________________________________+
.: .smtrace .i----------__----___________________+
j'15 \* I This is an internal word that supports the fsml trace capabilities. See ton and I
i~ \* I toff . I
,, \ ------ ----------________________________________+
: .metrace \ + ---- _------____--_________________________________________+
:~\* I This is an internal word that supports the fsml trace capabilities. See ton and i\* I toff .
---- ------------_------____--___________________________+
"~25 : inp>self .~;1\ +------ ---- ------------------------------------------------------------------------------------------------------------------------------------------------------_+
~\l I This word allows a machine instance to send an input to itself. This can also be I
c~\* I used for a submachine to send an input to its parent machine. I
:,....... \ * + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ +
~ 30 `` : submachine :~ \* +____________________________________________________________________________________+
:! \* I A submachine is similar to a machine, except that a submachine instance is a I
- \* 1 synchronoUs function that runs immediately in the task space of the task that I
c35 \* I executes it. The usual use of a submachine is to define it within the machine type I
.. I; \* I definition for a machine, although it is possible to define stand-alone 1 \* I submachines that do not run as separate tasks.
i:l\* I
;~l\* I Each submachine must be associated with a user variable, which will contain the I
~Sj40 \* I submachine's state value. Whereas a machine instance's inital state is defined by I
\* I the start-state word, a sUbmachine speCification does not use this mechanism. The I
\* I set-state word is used for this, and is usually executed in the prolog of the I
\* I parent machine. I
\* I EXAMPLE: I
,~i45 \* I user T.Null ( define submachine's user variable ) .L''~j \* I T.Null submachine >T.Null ( define submachine's access name ) ~3\* I
\* I
* I . I
~50 \* I
.,j\* I end-submachine ( submachine definition terminated by end-submachine ) '~i\* I
* I Submachine initialization code... usually in parent fsm's prolog section. I
~'\* I +-----------------Submachine state name `~l55 \* I I +------Submachine's user variable ;~\* I
.~i\* I V V
\* I Awaiting_Event.01 O.Null set-state .~,`\* I
\ + -------___---_________________________________________+
: end-submachine ---- ----------___------______________________+
\* j Defines the end of a submachine definition. See submachine .
65 \ + - -------_-----____________________________+
,:, : .
. ., :.~

. ., ....

' .
.; ~.
., et-state \* I Defines the initlal state of a submachine. See submachine . __+
----_____ ; decimal .. ( CODE FOR ERROR HELP ROUTINE FOR FSML -- errhelp ) (?) ( err# -- ) ( display help message ) + ----------------___________________________________________________________________________ \* I If you are compiling an fsm and get an error message, an error number will be I
\* I displayed. In order to translate the error number, type: <error#> (?) _------ _________________________+

~ 15 .

i i ., ..
~,, , ~;

..

:

:

:'` . ,: . ~ : - :

Claims (11)

1. A method for allowing a computer system to simu-late a system, said method comprising the steps of:
describing said system as a plurality of objects, said plurality of objects consisting of at least one con-trolling object;
defining said at least one controlling object as a finite state machine;
expressing said system as a plurality of finite state machines; and allowing communication between said plurality of finite state machines.

2. A method as claimed in claim 1 wherein said fi-nite state machine comprising:
a plurality of states that said finite state machine can assume;
a next state transition pair, for each of said plu-rality of states said next state transition pair de-scribes a next state for an input to said finite state machine;
an action routine for each of said next state tran-sition pair, said action routine describes what action said computer should take when said finite state machine transitions to said next state.

3. A method as claimed in claim 2 wherein said step of defining further comprising:
determining said plurality of states;
for each of said plurality of states, selecting only valid inputs;
mapping said next state for each of said valid in-puts; and describing said action routine for each of said valid inputs.

4. A method as claimed in claim 1 wherein said ob-jects comprising:
a plurality of data where said plurality of data describes said object; and a plurality of operations that can be performed by said computer system on said plurality of data.

5. A method as claimed in claim 5 wherein said step of describing further comprising the steps of:
finding a closet match between said object and a previously described object;
picking said closest match and creating a new object based on said closest match;
defining said plurality of data for said object; and describing said plurality of operations for said object.

6. A method for allowing a computer system to simu-late a system, said computer system being operated by a user through a user interface, said method comprising the steps of:
describing said system as a plurality of objects, said plurality of objects consisting of a controlling object;
defining said controlling object as a finite state machine; and allowing communication between said finite state machine and said user through said user interface, said user inputs stimules to said finite state machine and said user observes responses of said finite state machine to said input stimules.

7. A method as claimed in claim 6 wherein said fi-nite state machine comprising:
a plurality of states that said finite state machine can assume;
a next state transition pair, for each of said plurality of states said next state transition pair describes a next state for an input to said finite state machine;
an action routine for each of said next state tran-sition pair, said action routine describes said responses said computer will output to said user through said user interface when said finite state machine transitions to said next state.

8. A method as claimed in claim 7 wherein said step of defining further comprising:
determining said plurality of states;
for each of said plurality of states, selecting only valid inputs;
mapping said next state for each of said valid in-puts; and describing said action routine for each of said valid inputs.

9. A method as claimed in claim 6 wherein said ob-jects comprising:
a plurality of data where said plurality of data describes said object; and a plurality of operations that can be performed by said computer system on said plurality of data.

10. A method as claimed in claim 9 wherein said step of describing further comprising the steps of:
finding a closest match between said object and a previously described object;
picking said closest match and creating a new object based on said closest match;
defining said plurality of data for said object; and describing said plurality of operations for said object.

11. Each and every novel feature or novel combina-tion of features herein disclosed.