next up previous
Next: Operators in the group Up: Server stack machine Previous: Server stack machine

Operators in the group SMobject/Primitive

Any OX stack machine has at least one stack.

Object xxx_OperandStack[SIZE];
Here Object may be local to the system xxx wrapped by the stack machine. That is, the server may translate CMObjects into its local objects and push them onto the stack. It is preferable that the composition of such a translation and its inverse is equal to the identity map. The translation scheme is called the phrase book of the server and it should be documented for each stack machine. In OpenXM, any message is private to a connection. In future we will provide a content dictionary (CD; see OpenMath [4]) for basic specifications of CMObjects.

In the following, xxx_ may be omitted if no confusion occurs. As the names of functions and tags are long, one may use abbreviated names. Message packets are represented as follows.

Each field is shown as \fbox{data type \quad data}. For example int32 OX_DATA denotes a number OX_DATA which is represented by a 32 bit integer with the network byte order. If a field is displayed by italic characters, it should be defined elsewhere or its meaning should be clear. For example String commandName denotes a local object commandName whose data type is String. Note that an object on the stack may have a local data type even if it is represented as CMO.

Any server stack machine has to implement the following operations. For each operation we show the states of the stack before and after the operation. In the figures the rightmost object corresponds to the top of the stack. Only the modified part of the stack are shown.

1.

Any server should accept CMObjects in the group CMObject/Primitive. The server pushes such data onto the stack. The following examples show the states of the stack after receiving CMO_NULL or CMO_String respectively.

Request:
int32 OX_DATA int32 CMO_NULL

Stack after the request:
NULL

Output: none.

Request:
int32 OX_DATA int32 CMO_String int32 size byte s1 $\cdots$ byte ssize

Stack after the request:
String s

Output: none.

If the server fails to receive a CMO data,
int32 OX_DATA int32 CMO_ERROR2 CMObject ob

is pushed onto the stack. Currently ob is a list

[ Integer32 OX serial number, Integer32 error code, CMObject optional information]

2.
SM_mathcap

It requests a server to push the mathcap of the server. The mathcap is similar to the termcap. One can know the server type and the capability of the server from the mathcap.

@plugin/mathcap.h)

Request:
int32 OX_COMMAND int32 SM_mathcap

Stack after the request:
int32 OX_DATA Mathcap mathCapOb

Output: none.

3.
SM_setMathcap

It requests a server to register the peer's mathcap m in the server. The server can avoid to send OX messages unknown to its peer.

@plugin/mathcap.h)

Stack before the request:
Mathcap m

Request:
int32 OX_DATA Mathcap m
int32 OX_COMMAND int32 SM_setMathcap

Output: none.

Remark: In general the exchange of mathcaps is triggered by a client. A client sends SM_mathcap to a server and obtains the server's mathcap. Then the client registers the mathcap. Finally the client sends its own mathcap by SM_setMathcap and the server registers it.

4.
SM_executeStringByLocalParser

It requests a server to pop a character string s, to parse it by the local parser of the stack machine, and to interpret by the local interpreter. If the execution produces a Output, it is pushed onto OperandStack. If an error has occurred, Error2 Object is pushed onto the stack. OpenXM does not provide standard function names. If this operation and SM_popString is implemented, the stack machine is ready to be used as an OX server.

Stack before the request:
String commandString

Request:
int32 OX_COMMAND int32 SM_executeStringByLocalParser

Output: none.

Remark: Before this request, one has to push String commandString onto the stack. It is done by sending the following OX data message.

int32 OX_DATA int32 CMO_string size and the string commandString

5.
SM_executeStringByLocalParserInBatchMode

This is the same request as SM_executeStringByLocalParser except that it does not modify the stack. It pushes an Error2 Object if an error has occurred.

6.
SM_popString

It requests a server to pop an object from OperandStack, to convert it into a character string according to the output format of the local system, and to send the character string via TCP/IP stream. (char *)NULL is returned when the stack is empty. The returned string is sent as a CMO string data. CMO_ERROR2 should be returned if an error has occurred.

Stack before the request:
Object

Request:
int32 OX_COMMAND int32 SM_popString

Output:
int32 OX_DATA int32 CMO_STRING size and the string s

7.
SM_getsp

It requests a server to push the current stack pointer onto the stack. The stack pointer is represented by a non-negative integer. Its initial value is 0 and a push operation increments the stack pointer by 1.

Stack before the request:
Object

Request:
int32 OX_COMMAND int32 SM_getsp

Stack after the request:
int32 OX_DATA int32 CMO_INT32 stack pointer value

Output: none.

8.
SM_dupErrors

It requests a server to push a list object containing all error objects on the stack.

Request:
int32 OX_COMMAND int32 SM_dupErrors

Stack after the request:
int32 OX_DATA CMObject a list of errors  

Output: none.

Example: ox_sm1 returns the following data as its mathcap.

Class.mathcap 
 [ [199909080 , $Ox_system=ox_sm1.plain$ , $Version=2.990911$ , 
    $HOSTTYPE=i386$ ]  , 
   [262 , 263 , 264 , 265 , 266 , 268 , 269 , 272 , 273 , 275 , 276 ]  , 
   [[514] , [2130706434 , 1 , 2 , 4 , 5 , 17 , 19 , 20 , 22 , 23 , 24 , 
             25 , 26 , 30 , 31 , 60 , 61 , 27 , 33 , 40 , 34 ]]]

A mathcap has three components. The first one contains informations to identify the system and hosts on which the application runs. In the above example, Ox_system denotes the system name. HOSTTYPE represents the OS type and taken from $HOSTTYPE enviroment variable. The second component consists of avaiable SM commands. The third component is a list of pairs. Each pair consists of an OX message tag and the list of available message tags. Again in the above example, 514 is the value of OX_DATA and it indicates that the server accepts CMO (without size information) as mathematical data messages. In this case the subsequent list represents available CMO tags.

Example: We show examples of message_body. Serial numbers are omitted.

1.
executeStringByLocalParser("12345 ;");

is converted into the following packet. Each number denotes one byte in hexadecimal representation. (yy) in xx(yy) represents the corresponding ASCII code.

0   0   2   2   0   0   0   4   0   0   0   7  
31(1)  32(2)  33(3)  34(4)  35(5)  20  3b(;)   
0   0   2   1   0   0   1   c

Each data has the following meaning.

0   0   2   2  (OX_DATA) 0   0   0   4  (CMO_STRING)
0   0   0   7  (size)
31(1)  32(2)  33(3)  34(4)  35(5)  20  3b(;)   (data)
0   0   2   1  (OX_COMMAND) 
0   0   1   c  (SM_executeStringByLocalParser)
This is expressed by OXexpression as follows.
(OX_DATA, (CMO_STRING, 7, "12345 ;"))
(OX_COMMAND, (SM_executeStringByLocalParser))

2.
A message which requests SM_popString:
0   0   2   1  (OX_COMMAND) 
0   0   1   7  (SM_popString)
In OXexpression it is represented as (OX_COMMAND, (SM_popString)).

The server returns the following reply message:

0   0   2   2   (OX_DATA) 
0   0   0   4   (CMO_STRING) 0   0   0   5  (size)
31(1)  32(2)  33(3)  34(4)  35(5)
In OXexpression it is represented as (OX_DATA, (CMO_STRING, 7, "12345 ;")).


next up previous
Next: Operators in the group Up: Server stack machine Previous: Server stack machine
Nobuki Takayama 平成12年1月25日