The RUV System in J-Sim

In this document, we give the overview or the RUV system and a summary of all the RUV system commands in the J-Sim environment. One can also use the "man" command in a tcl terminal for a list of available commands, or use "man <command>" for a detailed description of how a specific command works.

• List of Commands
• 1. RUV System
• 2. Path Expression
• 3. Common Command Options
• 4. Detailed Command Description 

List of Commands

Basic commands

UNIX-like commands	! !! !!! cat cd cp ls man mkdir mv pwd rm.
attach_simulator	attach a simulation runtime to components.
connect/disconnect	connect/disconnect components/ports.
attach/detach		attach/detach an instrument port.
pipe			connect/break a series of components/ports in a pipe manner.
watch			add/remove a system watcher.
setflag/getflag		set/display component flags.
run/stop/reumse		start/stop/resume components.
reset			reset components.
reboot			reset components and runtime.
rt			access runtime.
inject			inject data to ports.
set_default_class	set the default class for 'mkdir'.
whats_default_class	return the name of the default class for 'mkdir'.
term			create a new terminal.
exit			exit the terminal.
quit			quit the program.

Execution control

script			schedule a script.
wait_until		block the terminal until a condition becomes true.

Topology exploration

explore			explore the component topology from a component.

Verification

verify			verify connections within a composite component.

Other utility commands

grep			search a pattern in a text and prints the result.
subtext			extract lines of text from a text.
nlines			counts the number of lines in a text.
_to_string_array	convert a Tcl list to a Java(TM) array of String.

1 The RUV System

The structure of the RUV system is as follows:

/ The root component.
 +--- .term		Place that holds terminal and shell components.
 |     +--- tcl0		A terminal.
 |     +--- tcl0_shell	The TCL shell associated with tcl0.
 |     +--- backup	A backup TCL shell for diagnosis purpose. 
 |
 +--- .system 		Place that holds system objects.
       +--- monitor 	The system monitor that listens to the ".info@" ports of all the components in the system.
       +--- rt 		An instance of java.lang.Runtime.

The output is re-organized in the RUV system as follows:

Figure 1: The system components in the RUV system.

Figure 2: The output structure in the RUV system.

Specifically, the standard output (java.lang.System.out) and error (java.lang.System.err) are redirected to the terminals via drcl.ruv.RUVOutputManager, and a terminal displays the messages on its screen and also output them to drcl.ruv.RUVOutputManager.SYSTEM_OUT which is the original java.lang.System.out, if the "stdout" flag is enabled. Consider the following output paths:

1. The result of executing a script command is sent back from the shell to the terminal. The terminal displays the result in its screen and also outputs it to drcl.ruv.RUVOutputManager.SYSTEM_OUT.
2. A component exports some runtime information at its ".info@" port. The message is received by the "/.system/monitor" component and is outputted to java.lang.System.out which is redirected to the terminals and SYSTEM_OUT via drcl.ruv.RUVOutputManager.
3. A class outputs some error messages via drcl.Debug.error() which prints out the messages on java.lang.System.err which is, in turns, redirected to the terminals and SYSTEM_OUT via drcl.ruv.RUVOutputManager.

2 Path Expression

Many RUV commands contain one or more paths in their argument list. A path uniquely identifies a component or a port in a component hierarchy.  The expression of a path is exactly the same as that in a file system. For example, the "wildcard" path expression refers to multiple components. In addition to the wildcard characters "*" and "?", RUV has other powerful path expressions, which we discuss below:

Wildcard Characters

One may include "*" and "?" in a path expression. For example, "USA/O*" matches all the state components with names starting with "O" (suppose "USA" is a component hierarchy that contains all the states and cities in the United States). "USA/O??o" matches all the states whose names consist of four letters, beginning with "O" and ending with "o". It is also possible to use "[]" to include all the characters to be matched. For example, "{n[23][01]}" matches "n20", "n21", "n30" and "n31".

 

Range Specification

One may use the range expression "<n>-<m>" to specify a range of components. For example, "n3-n10" matches components "n3", "n4", ..., and "n10".

 

Partial Path

One may also use "..." to specify all the components that match the partial path. For example, "USA/.../Columbus" matches "USA/Ohio/Columbus", "USA/Georgia/Columbus", "USA/Indiana/Columbus", "USA/Mississippi/Columbus", "USA/Nebraska/Columbus" and "USA/Columbus" (suppose Columbus is also a state in the United States).

 

Enumeration Specification

One may enumerate all the sub-paths in a path specification. For example, "USA/Ohio,Georgia/Columbus" matches "USA/Ohio/Columbus" and "USA/Georgia/Columbus". If an enumerated sub-path contains "/", then "<>" must be used to make the expression clear. For example, "USA,<USA/Ohio>/Columbus" matches "USA/Columbus" and "USA/Ohio/Columbus".

 

Component Reference

One may use the reference of a component at the beginning of a path expression. For example, if the Tcl variable "x" references to the "USA" component, then "$x/.../Columbus" is the same expression as "USA/.../Columbus".

One may use some or all the above wildcard characters and component references to generate powerful expressions. For example, "$x/g?mma3-7/.../s*lar/.../?ar??" would match "$x/gamma3/solar/earth" and "$x/gemma7/beta/scholar/Harry".

3 Common Command Options

There are three common options for commands that are related to path expressions. By default (if no option is specified), a path expression matches only non-hidden (i.e., ID does not start with ".") components (not ports):

-a	Match all hidden components (and ports if -p is specified).
-p	Match port as well.
-q	Suppress verbose warnings such as "invalid path".

4 Detailed Command Description

!

 

Convert the path to the reference to the Java object and then invoke the method specified in the argument list.

 

SYNOPSIS

! ?-apq? <path> ?<method> ?<arg>...??

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match port as well.
-q	Suppress verbose warnings such as "invalid path".

!!

 

Convert the paths to a Java Object array of the referenced Java objects.

 

SYNOPSIS

!! <path1> ?<path2>...?     

NOTE

 

A path can be set to [java::null].

!!!

 

Cast the object reference to its most specific class.

 

SYNOPSIS

!!! <Java_object_ref>     

attach

 

Attach an intrument port.

SYNOPSIS

attach ?-acpq? <instrument_port_path>... -to|-with <destination_path>...

OPTION

-a	Match all hidden components (and ports if -p is specified).
-c	Create ports if the specified ports do not exist.
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".
-to	Make the intrument port listen to what comes out of the specified ports.
-with	Make the intrument port listen to what the specified ports receive.

DESCRIPTION

 

The command attaches the instrument port(s) to the ports specified in the destination path(s). It differs from the connect command in that the attach command does not result in joining of the connections of the specified ports.

 

SEE ALSO

detach, connect.

attach_simulator

 

Attach a simulation runtime to components.

 

SYNOPSIS

attach_simulator ?-aq? ?<#threads allowed> | event? <path1> ?<path2>...?

OPTION

-a	Match all hidden components.
-q	Suppress verbose warnings such as "invalid path".
event   Use sequential event simulation runtime rather than the real-time one.

DESCRIPTION

 

The command attaches a default simulation runtime to components specified in the path(s). If # of threads allowed is not specified, the runtime creates as many threads as possible if needed.

 

cat

 

Print the values of a java object, or the internal state (using Component.info(), Port.info()), and/or the connections, of a component/port.

SYNOPSIS

cat ?-acdhnpqt? ?<path>...?
cat <Java_object_ref>

OPTION

-a	Match all hidden components (and ports if -p is specified).
-c	Display only the connections for a component.
-d	Display both the internal states and the connections in details
	for a component.
-h	Display hidden ports when displaying connections (-c).
-n	Display ports that do not connect to other ports when displaying
	connections (-c).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".
-t	Display the port type when displaying connections (-c).

NOTE

 

The second form is particularly useful in examining the contents of a Java array.

cd

 

Change the current working directory.

SYNOPSIS

cd ?-aq? ?<path>?

OPTION

-a	Match all hidden components.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

If multiple components are matched to the path, the first matched component becomes the current working directory. No specific rule is defined in determining the first match.

connect

 

Connect components/ports.

SYNOPSIS

connect ?-acpqs? <source_path>... -to|-and <destination_path>...

OPTION

-a	Match all hidden components (and ports if -p is specified).
-and	Set up a bidirectional connection.
-c	Create ports if the specified ports do not exist.
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".
-s	Set up one shared bidirectional connection (with -and).
-to	Set up a unidirectional connection.

DESCRIPTION

 

The command connects components/ports in the source path(s) and components/ports in the destination path(s). If components are specified, the command first finds ports available in the components in order to set up the connection.

A bidirectional connection either consists of two unidirectional connections or one shared connection. By default (no -s option), the command creates two unidirectional connections in response to the -and option.

The original connections (if exist) of the ports will be joined all together after connect.

 

SEE ALSO

disconnect.

cp

 

Copy components/ports.  This command returns the reference of the object(s) being copied.

SYNOPSIS

cp ?-apq? <source_path>... <destination_path>
cp ?-apq? <source_path>... -d <destination_path>...

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The first form copies (using Component/Port.duplicate(Object)) all the components matched with the source path(s) under the destination path. If only one component is matched in the source path(s), then the destination path may be specified as the path of the clone of the source, provided that the component with the destination path does not exist and the parent of the destination path exists. Note that the destination path may match multiple components.

The second form copies all the components matched with the source path(s) under multiple destination paths. It has the same effect as executing the command of the first form on the destination paths one by one.

detach

 

Detach an instrument port.

SYNOPSIS

detach ?-apq? <instrument_port_path>... -to|-with <destination_path>...

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".
-to	Remove the instrument port from listening to what comes out of the specified ports.
-with	Remove the instrument port from listening to what the specified ports receive.

DESCRIPTION

 

The command detaches the instrument port(s) from the ports specified in the destination path(s).

SEE ALSO

attach.

disconnect

 

Disconnect components/ports.

SYNOPSIS

disconnect ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

If components are specified in the path(s), all the ports of the components are disconnected from the other parts of the system.

SEE ALSO

connect.

exit

 

Close the current terminal. If the current terminal is the last one, then the command exits Java.

explore

 

Explore and print the component topology.

SYNOPSIS

explore ?-afq? <path_of_starting_component> ?-transparent <path>...? ?-excluded <path>...?

OPTION

-a			Match all hidden components.
-excluded <...>		Exclude the components from being explored.
-f                      Discover the "flat" topology of all "leaf" components reached.
-q			Suppress verbose warnings such as "invalid path".
-transparent <...>	Make the components transparent in the exploration.

DESCRIPTION

 

This command explores the component topology by tracing from the starting component, all the way to the root component. During the exploration process, if the -f flag is not on (default), the command does not trace into a containing component. As a result, the components that can be traced from the starting component are at the same (component hierarchy) layer as, or higher layer than, the starting component.

One may specify components (in the -transparent option) as transparent during the course of exploration. Also components may be (in the -excluded option) excluded from the topology exploration.

getflag

 

Display the flags of the given components.

SYNOPSIS

getflag ?-adlpq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-d	Display disabled flags as well.
-l	Display all the programmable flags.
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

This command displays the flags of the given components.  By default, this command only examines the following component flags and display enabled ones: Trace, Garbage, GarbageDisplay, Debug, ErrorNotice and EventExport. The option "-l" makes the command examine all the programmable flags. A programmable flag is found by discovering the pair of the "read" method, is<flag>Enabled(), and the "write" method, set<flag>Enabled(boolean), in the component (or more precisely, in the component's JavaBeans properties). With the "-d" option, the command displays not only the enabled flags but also the disabled ones, for reference purpose.

SEE ALSO

setflag.

grep

Search a pattern in a text and print the lines that contain the pattern.

SYNOPSIS

grep <pattern> <text>     

inject

 

Inject data to ports.

 

SYNOPSIS

inject ?-apq? <data> <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

ls

 

List the child components (and ports).

SYNOPSIS

ls ?-apql? ?<path>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-l	List in the long format (more detailed information).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

mkdir

 

Create components/ports.  This command returns the reference of the object(s) being created.

SYNOPSIS

mkdir ?-aq? <Java_class_name> <path1> ?<path2>...?
mkdir ?-aq? <Java_object_ref> <path1> ?<path2>...?
mkdir ?-aq? <port_path1> ?<port_path2>...?
mkdir ?-aq? <component_path>

OPTION

-a	Match all hidden components.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command creates one or more components/ports in the path(s) specified. If the class name or the Java object is not a component/port, a wrapper component (drcl.comp.WrapperComponent) is created to encapsulate the object.

The fourth form uses the default class to create component(s) at the specified path. It is equivalent to "mkdir ?-aq? <default_class> <component_path>".

SEE ALSO

set_default_class, whats_default_class.

mv

 

Move components/ports.  This command returns the reference of the object(s) being moved.

SYNOPSIS

mv ?-apq? <source path>... <destination path>
mv ?-apq? <source_path>... -d <destination_path>...

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command moves components/ports specified in the source path(s) to the destination path. The command does not change the connections of the moved components/ports.

The second form of this command is the same as "cp" except that the source components are removed from the original directories and moved to the first directory component specified in the destination path(s).

SEE ALSO

disconnect.

nlines

 

Count and print the number of lines in a text.

SYNOPSIS

nlines <text>     

pipe

 

Connect/break a series of components/ports in a pipe manner.

SYNOPSIS

pipe ?-a? ?-connect|-break? <path1> <path2>...

OPTION

-a		Form the pipe by "attach" instead of "connect".
-connect	Connect a pipe, the default action if none is specified.
-break		Break a pipe.

DESCRIPTION

 

The command connects (or breaks) a series of components/ports specified in the path(s) to form a "pipe". Specifically, the first port is connected to (or attached to by) the second port, the second port is connected to (or attached to by) the third port and so on.

 

If components are specified, the command first finds ports available in the components in order to set up the pipe.

SEE ALSO

attach, connect.

pwd

 

Print the current working path.

reboot

 

Reset components and the runtime(s) behind components.

SYNOPSIS

reboot ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command calls drcl.comp.Component.reboot() for all the components specified in the path(s).

SEE ALSO

reset.

reset

 

Reset components.

SYNOPSIS

reset ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command calls drcl.comp.Component.reset() for all the components specified in the path(s).

SEE ALSO

reboot.

resume

 

Resume (stopped) components and all the subcomponents within.

SYNOPSIS

resume ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

SEE ALSO

run, stop.

rm

 

Remove components/ports.  This command returns the object(s) being removed.

SYNOPSIS

rm ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command removes the components/ports specified by the path(s). The command does not disconnect the removed components.

SEE ALSO

disconnect.

rt

 

Access runtime and its information.

SYNOPSIS

rt ?-apq? <path> ?<method> ?<arg1>...??

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command retrieves the runtime behind the component specified, and does a method call if a method is specified.

run

 

Start components and all the subcomponents within.

SYNOPSIS

run ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

SEE ALSO

stop, resume.

script

 

Execute a script at a future time instant (recursively).

SYNOPSIS

script <script> ?-at <time> ?later?? ?-period <period>? ?-on <runtime_instance>?
     ?-shell <shell_instance>?

OPTION

-at <...>	The time instance to execute this script the first time
      ?later?	(default: 0.0).  The time instance is relative if "later" is
		present.
-period <...>	Execute this script periodically (default: 0.0, execute only one time).
-shell <...>	Associate execution of this script to the shell (default:
		the current shell instance).
-on <...>	Associate execution of this script to the runtime instance
		(default: the default runtime instance).

setflag

Turn on/off the given flags on the components/objects.
     

SYNOPSIS

setflag ?-apq? <flag>... <enabled> ?-at <list_of_debug_levels>?
	?<recursively>? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-at	Enable/disable debug levels.
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

 

The command enables/disables the given flag(s) on the matched components/objects. Six flags are defined for drcl.comp.Component: Trace, Garbage, GarbageDisplay, Debug, ErrorNotice and EventExport. Additional flags that are defined in sub-components or objects may be enabled/disabled by this command as well.

A component may define debug levels to further classify debug messages. Each level can be enabled/disabled individually with the "-at" option. Enabling the debug flag of a component without specifying debug levels enables the debug flag and all the debug levels if defined. Available debug levels can be shown with the getflag command.

SEE ALSO

getflag.

set_default_class

 

Set the default class for 'mkdir'.

SYNOPSIS

set_default_class ?class_name?

DESCRIPTION

 

This command sets the default class for 'mkdir' a component without the class or object argument. If the class name is not specified, 'drcl.comp.Component' is set as the default.

SEE ALSO

mkdir, whats_default_class.

stop

 

Stop components and all the subcomponents within.

SYNOPSIS

stop ?-apq? <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

SEE ALSO

run, resume.

subtext

Extract lines from a text.

SYNOPSIS

subtext <text> <start line #> <end line #>
     

term

 

Create a new terminal.

SYNOPSIS

term <title> ?-t <terminal_class>? ?-s <shell_class>|<shell_object>? ?<init_script>?

OPTION

-t <...>	The terminal class.
-s <...>	The shell class or object.

DESCRIPTION

 

This commands creates a new terminal. One may specify the terminal class, the shell class or object to be associated with the terminal, and/or the initial script to execute.

wait_until

 

Block the terminal input until the specified condition becomes true.

SYNOPSIS

wait_until <condition>

DESCRIPTION

 

<condition> is a script that returns a boolean value (0 or others). This command can only be used as a standalone command. The result will not be predictable if it is invoked inside other commands such as "if".

watch

 

Add/remove a system watcher at the system monitor /.system/monitor. The events observed by the watcher are output to whichever components that are connected to the system monitor.

SYNOPSIS

watch ?-acpq? ?-label <label>? -add|-remove <path1> ?<path2>...?

OPTION

-a	Match all hidden components (and ports if -p is specified).
-c	Create ports if the specified ports do not exist.
-label	The watcher label
-p	Match ports as well.
-q	Suppress verbose warnings such as "invalid path".

DESCRIPTION

The command attaches a port of the RUV system watcher component to the ports specified in the destination path(s). Then the watcher port starts to listen to what comes out of the specified ports and prints whatever it receives on the terminal. One may add and remove multiple watchers in a command. For example, "watch -label L1 -add x@p1 y@p2 -remove z@p3 -label none -add w@p4 u@p5" adds x@p1 and y@p2 to the L1 watcher and removes z@p3 from the L1 watcher, and adds w@p4 and u@p5 to the default watcher (with no label).

whats_default_class

 

Print the name of the default class for 'mkdir'.

 

SEE ALSO

mkdir, set_default_class.

Last updated: June 21, 2002.