\documentclass{howto}

\usepackage{hyperref}
\hypersetup{%
  colorlinks=true,
  plainpages=false,
}

\title{ROVM Client Document}
\author{Weongyo Jeong}
\authoraddress{
  \strong{Australia Melbourne}\\
  email : \email{weongyo@gmail.org}
}
\date{2006.3.20}

\begin{document}
\maketitle

\begin{abstract}
  \noindent
  This document explains how ROVM Client can communicate with ROVM Server.
  Also, the commands and functions of ROVM Client are described.
\end{abstract}

\tableofcontents

\section{Introduction}
\label{sec:introduction}

ROVM Client is a part of ROVM project and is made for communicating with 
ROVM Server.  Using ROVM Client, you can connect ROVM Server and debug 
your opcodes easily.

ROVM Client parses your inputs and converts to a binary code which ROVM 
Server can understand.  Also, ROVM Client sends the opcodes of user and 
processes the result which be received from ROVM Server.  You can understand
easily.

ROVM Client's code is python code and a look is similar with python
interpreter.

\section{Execution}
\label{sec:exec}

ROVM Client consists of one python file and you can see `prompt' if you run it.

\begin{verbatim}
C:\rovmclient> python rovmclient.py
ROVM Client 0.0.1a
Type "help" for more information.
>>> 
\end{verbatim}

You can see a help messages of ROVM Client typing `help' command on your
screen.

If you want to see a detail infomation for each commands, type `help \texttt{<command>}'

\begin{verbatim}
>>> help

Normal mode commands
-----------------------------------------------------------------
 help         Show this message.
 opcode       Entering OPCODE mode.
 printopcode  Print saved opcodes.
 quit         Exit rovmclient.
 req <URL>    Get Ticket.
 reqend       Remove Ticket.
 send         Send opcodes.
 stack        Print remote stack status.
-----------------------------------------------------------------
If you want to see a detailed explanation, Type `help <command>'.

>>> help req
\end{verbatim}

The prompt of ROVM Client is same with the prompt of python.  Also,
there is another prompt `\texttt{...}'.  This prompt is explained at
\ref{sec:modeopcode} section.

\section{Modes}
\label{sec:mode}

In case of ROVM Client, Current there are two modes which are `execute mode' 
and `opcode mode' and each mode is for another purpose.  `execute mode' is
a normal normal.  `opcode mode' is for inputing opcodes.

`execute mode' is used for getting a new Ticket ID, sending a reserved
commands or getting the server status.  These commands belongs to `execute mode'

`opcode mode' is used for making opcodes of ROVM Server.

\subsection{Execute Mode}
\label{sec:modecommand}

\subsubsection{HELP}

Print the help messages.

Format : help \\
Example :
\begin{verbatim}
>>> help

Normal mode commands
-----------------------------------------------------------------
 help         Show this message.
 opcode       Entering OPCODE mode.
 printopcode  Print saved opcodes.
 quit         Exit rovmclient.
 req <URL>    Get Ticket.
 reqend       Remove Ticket.
 send         Send opcodes.
 stack        Print remote stack status.
-----------------------------------------------------------------
If you want to see a detailed explanation, Type `help <command>'.

>>>
\end{verbatim}

\subsubsection{OPCODE}

Enter opcode mode.

ROVM Client has two modes.  The first mode is `execute mode' which has
a prompt started with `\texttt{>>>}'.  The second mode is `opcode mode' which
has a prompt started with `\texttt{...}'.

This command is used for entering opcode mode.  If you want to exit from opcode
mode, just type \texttt{<ENTER>} key.

The opcodes which have been inputed are saved automatically and will be send
to ROVM Server when the user executes `SEND' command.

You don't need to type all of codes at a time.  For example, you can just input 1 opcode
and send your opcode to ROVM Server.  By using `STACK' command, you can always
get the status information of the stack on Ticket ID.

Format : opcode \\
Example :
\begin{verbatim}
>>> opcode
... <Current you entered in opcode mode>
\end{verbatim}

\subsubsection{PRINTOPCODE}

Print the list of opcodes which be inputed by a user.

Using this command, you can check opcodes which inputed and you can
check how your input is converted to.

Format : printopcode \\
Example :
\begin{verbatim}
>>> opcode
... cpush 1
... cpush 2
...
>>> printopcode
#0 (02) '\x10\x01'
#1 (02) '\x10\x02'
\end{verbatim}

\subsubsection{QUIT}

Terminate ROVM Client application.

\subsubsection{REQ}

Get a new Ticket ID.

In ROVM world, if you want to execute some opcodes on remote ROVM Server,
you need a permission of server.  `REQ' command provides a method to get
a permission of server.  After getting a permission, all commands will enclose 
a ticket id at their packets.

In case of `URL address', you must follow a format which 
is e://\texttt{<hostname>}:\texttt{<port>}.  `\texttt{<hostname>}' can be
\emph{192.168.23.234} or \emph{www.blahblah.org}.  `\texttt{<port>}' is
the port of server.

If you want to connect ROVM Server with the authentication, you should
use e://\texttt{<userid>}@\texttt{<hostname>}:\texttt{<port>} format.

Format : req \texttt{<URL address>} \\
Example :
\begin{verbatim}
>>> req e://192.168.59.128:8889
>>> req e://rovm@192.168.58.129:4390
\end{verbatim}

If you use the authentication, ROVM Client will ask the password.

\begin{verbatim}
C:\>python rovmclient.py
ROVM Client 0.0.1h
Type "help" for more information.
>>> req e://rovm@192.168.58.129:4390
Enter password:
\end{verbatim}

\subsubsection{REQEND}

Destory a Ticket ID.  If you send this command to server, ROVM Server
releases all structures and memory allocations related with Ticket ID.

Format : reqend \\
Example :
\begin{verbatim}
>>> req e://192.168.59.128:8889
>>> reqend
\end{verbatim}

\subsubsection{SEND}

Send opcodes which be inputed by a user to ROVM Server.  Before you 
execute this command, you mush get a ticket from server.

Format : send \\
Example :
\begin{verbatim}
>>> req e://192.168.59.128:8889
>>> opcode
... <Input some opcodes that you want to run.>
... <ENTER>
>>> send
\end{verbatim}

\subsubsection{STACK}

Print the status of the stack.

Format : stack \\
Example :
\begin{verbatim}
>>> req e://192.168.59.128:8889
>>> opcode
... <Input some opcodes that you want to run.>
... <ENTER>
>>> send
>>> stack
<The contents of the stack>
\end{verbatim}

\subsection{Opcode Mode}
\label{sec:modeopcode}

If you want to enter `opcode mode', you can do it by typing `opcode'
command at `execute mode'.

\begin{verbatim}
>>> opcode
...
\end{verbatim}

`\texttt{...}' prompt points that you are in `opcode mode'.  
If you want to exit `opcode mode', just type \texttt{<ENTER>} key.

\begin{verbatim}
... <ENTER>
>>>
\end{verbatim}

In opcode mode, you also can see help messages about how you can use
opcodes.  By typing `help' command, you can see it.

\begin{verbatim}
... help

Opcode mode commands
-----------------------------------------------------------------
 cpush <Char Number>
              Push `char type' number.
 iadd         Add int.
 <ENTER>      Escape opcode mode
-----------------------------------------------------------------
If you want to see a detailed explanation, Type `help <command>'.

\end{verbatim}

\subsubsection{BPUSH}

Push a boolean.  If 1 means TRUE, 0 means FALSE.

Number : 13 (0xd) \\
Format : bpush \texttt{<1 byte unsigned char>} \\
Stack : (...) $\rightarrow$ (..., \texttt{\emph{<boolean>}}) \\
Example :
\begin{verbatim}
... bpush 0
... bpush 1
\end{verbatim}

\subsubsection{CPUSH}

Push a char.  It's same with C type `char'

Number : 16 (0x10) \\
Format : cpush \texttt{<1 byte number>} \\
Stack : (...) $\rightarrow$ (..., \texttt{\emph{<byte number>}}) \\
Example :
\begin{verbatim}
... cpush -128
... cpush 127
\end{verbatim}

\subsubsection{HPUSH}

Push a short.  It's same with C type `short'

Number : 17 (0x11) \\ 
Format : hpush \texttt{<2 byte short>} \\
Stack : (...) $\rightarrow$ (..., \texttt{<short>}) \\
Example :
\begin{verbatim}
... hpush 12332
... hpush -123
\end{verbatim}

\subsubsection{IPUSH}

Push a int.  It's same with C type `int'

Number : 18 (0x12) \\
Format : ipush \texttt{<4 byte signed number>} \\
Stack : (...) $\rightarrow$ (..., \texttt{\emph{<int number>}}) \\
Example :
\begin{verbatim}
... ipush -2147483648
... ipush 2147483647
\end{verbatim}

\subsubsection{FPUSH}

Push a float.  It's same with C type `float'.

Number : 14 (0xe) \\
Format : fpush \texttt{<4 byte float>} \\
Stack : (...) $\rightarrow$ (..., \texttt{<float>}) \\
Example :
\begin{verbatim}
... fpush 123.0
\end{verbatim}

\subsubsection{DPUSH}

Push a double.  It's same with C type `double'.

Number : 15 (0xf) \\
Format : dpush \texttt{<8 byte double>} \\
Stack : (...) $\rightarrow$ (..., \texttt{<double>}) \\
Example :
\begin{verbatim}
... dpush 123123.0
\end{verbatim}

\subsubsection{SPUSH}

Push a string.  A string which be pushed changes to StringRef automatically.
The size of opcode has variable size.

Number : 19 (0x13) \\
Format : spush ``\texttt{<string>}'' \\
Stack : (...) $\rightarrow$ (..., \texttt{\emph{<StringRef>}}) \\
Example :
\begin{verbatim}
... spush "Hello! ROVM Server"
... spush "I love you."
\end{verbatim}

\subsubsection{DUP}

Duplicate the top stack value.

Number : 89 (0x59)
Format : dup
Stack : (..., \texttt{<value>}) $\rightarrow$ (..., \texttt{<value>}, \texttt{<value>})
Example :
\begin{verbatim}
... spush "Hello! ROVM Server"
... dup
\end{verbatim}

\subsubsection{IADD}

Add int.  Both \emph{value1} and \emph{value2} must int type.  The values are poped from the 
stack.  The int \emph{result} is \emph{value1} + \emph{value2}.

Number : 90 (0x60) \\
Format : iadd \\
Stack : (..., \texttt{\emph{<value1>}}, \texttt{\emph{<value2>}}) $\rightarrow$ (..., \texttt{\emph{<result>}}) \\
Example :
\begin{verbatim}
... cpush 1
... cpush 2
... iadd
\end{verbatim}

\subsubsection{CALL}

Call a instance method; dispatch based on class.

Number : 182 (0xb6) \\
Format : call \texttt{<name>} \texttt{<type>} \\
Stack : (..., \emph{objectref}, [\emph{arg1}, [\emph{arg2} ...]]) -> (...) \\
Example :
\begin{verbatim}
... call __init__ (S)V
... call abc (SII)I
\end{verbatim}

\subsubsection{NEW}

Create new object.  Memory for a new instance of that class is allocated from 
the garbage-collected heap.  If ROVM Server can't find that class or can't be loaded, Server sends
`ERROR' messages to the client or server.

Number : 187 (0xbb) \\
Format : new \texttt{e://<hostname>[:<port>]<path>} \\
Stack : (...) $\rightarrow$ (..., \texttt{\emph{<objectref>}}) \\
Example :
\begin{verbatim}
... new e://192.168.58.129:4390/testsuite/insert
... new e://envlang.kldp.net/testsuite/insert
\end{verbatim}

\subsubsection{NEWARRAY}

Create new array.  The count must be of type int. It is popped off the stack. 
The count represents the number of elements in the array to be created.
A new array whose components are of length \emph{count} is allocated from 
the garbage-collected heap.
A reference \emph{ArrayRef} to this new array object is pushed into the 
operand stack.

Number : 188 (0xbc) \\
Format : newarray \texttt{<type number>} \\
Stack : (..., \texttt{\emph{<count>}}) $\rightarrow$ (..., \texttt{\emph{<arrayref>}}) \\
Example :
\begin{verbatim}
... ipush 256
... newarray 3
\end{verbatim}

\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: