
                  kapy: a prototype of KANT SCSCP client shell
                  ============================================

===============================================================================
Copyright:
==========

Authors: Lesseni Sylla <lesseni@math.tu-berlin.de>
         Sebastian Freundt <freundt@math.tu-berlin.de>

kapy is licensed according to the terms of the License as 
published from the KANT/KASH system website at:
http://www.math.tu-berlin.de/~kant/copyrigth.html

==============================================================================


kapy is the new KANT SCSCP client shell and it stands for KANT python. 
It is written in python language and fully supports SCSCP version 1.3.

Prerequisites:
============== 
To use kapy you need:
- to download the freely available KANT/KASH SCSCP package (autokash). 
For more informations see the public website at: 
http://www.math.tu-berlin.de/~kant/kantscscp.html
- at least python 2.5.2 
- and at least libxml2.4.0 (provided with autokash)

How to use kapy:
===============
We put by default the kapy script under the pysh/ directory.
Using kapy as explain in the next steps one can connect to the running
KANT SCSCP server (the running kashd process) or any configured SCSCP
server.  
The use instructions of kapy are the followings:
Step 1:
------
Run the kashd daemon in a shell by typing this command (see autokash package): 

===============================================================================

shell> bin/kashd lib/kant/openmath.la &

===============================================================================

Step 2:
-------
Open another shell and go to the directory where kapy is installed 
(in the pysh/ directory) and type python like this:

===============================================================================

shell:pysh>python
Python 2.5.2 (r252:60911, Dec  1 2008, 18:10:01)
[GCC 4.3.1 20080507 (prerelease) [gcc-4_3-branch revision 135036]] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
===============================================================================

Step 3:
-------
===============================================================================

>>>import kapy

============================================================================== 

Step 4:
------
The connection to the running SCSCP server needs the server name 
(the hostname, which could be for example localhost or issel.math.tu-berlin.de
or stirling.math.tu-berlin.de) and its port number 26133.
Note that the port number 26133 is reserved for SCSCP by Internet 
Assigned Numbers Authority (IANA).

===============================================================================

>>> cas = kapy.connect("localhost", 26133);
Handshake succeeded
>>>
in case you run locally the kashd daemon, or

>>> cas = kapy.connect("issel.math.tu-berlin.de", 26133)
Handshake succeeded
>>>
in case you connect to the running server at TU Berlin, Germany.
===============================================================================

Step 5:
------
The succeded result (Handshake succeeded) of the previous step means 
that the communication with the running SCSCP server is accepted. 
Now we can begin the communication with the server.
Note that at this level the argument of the procedure_call looks like:

===============================================================================

>>>kapy.oma("cd_name", "symbol_name", arguments)

===============================================================================

in case of an openmath application

===============================================================================

>>>kapy.oms("cd_name", "symbol_name")

===============================================================================

in case of an openmath symbol.
Example 1:
---------

===============================================================================

>>> cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("list1", "list", 1,2))));
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMA><OM:OMS cd="list1" name="list"/><OM:OMI>1</OM:OMI><OM:OMI>2</OM:OMI></OM:OMA></OM:OMA></OM:OMATTR></OM:OMOBJ>
<xmlNode (OMOBJ) object at 0x14c8200>
>>> 
>>>
>>> K=kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("arith1", "minus", kapy.oma("arith1", "power", 2, 127), 1)));
>>>
>>> print K;
<OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR><OM:OMS cd="scscp1" name="option_return_object"/><OM:OMSTR> </OM:OMSTR></OM:OMATP><OM:OMA><OMS cd="scscp1" name="procedure_call"/><OM:OMA><OMS cd="arith1" name="minus"/><OM:OMA><OMS cd="arith1" name="power"/><OM:OMI>2</OM:OMI><OM:OMI>127</OM:OMI></OM:OMA><OM:OMI>1</OM:OMI></OM:OMA></OM:OMA></OM:OMATTR>
>>> 
>>> cas.compute(K);
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMI>170141183460469231731687303715884105727</OM:OMI></OM:OMA></OM:OMATTR></OM:OMOBJ>
<xmlNode (OMOBJ) object at 0x14c8050>
>>> 
===============================================================================

Example 2:
---------

===============================================================================
>>> cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oms("ringname1", "Z"))));
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMS cd="ringname1" name="Z"/></OM:OMA></OM:OMATTR></OM:OMOBJ>
<xmlNode (OMOBJ) object at 0x14c80e0>
>>> 
>>>
>>> L=kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oms("setname1", "C")));
>>>
>>> print L;
<OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR><OM:OMS cd="scscp1" name="option_return_object"/><OM:OMSTR> </OM:OMSTR></OM:OMATP><OM:OMA><OMS cd="scscp1" name="procedure_call"/><OM:OMS cd="setname1" name="C"/></OM:OMA></OM:OMATTR>
>>>
>>> cas.compute(L);
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMS cd="fieldname1" name="C"/></OM:OMA></OM:OMATTR></OM:OMOBJ>
<xmlNode (OMOBJ) object at 0x14c81b8>
>>> 
>>>
===============================================================================

We can assign the result of a request to a variable to reuse within 
new requests. In this case, we compute that intermediate result 
with the function compute_intermediate instead of the function compute 
to extract the procedure_terminated part.
Example 3:
---------

===============================================================================

>>> A=cas.compute_intermediate(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "123.omsymcom:lesseni:26134", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("list1", "list", 1,2))));
<OM:OMA><OM:OMS cd="list1" name="list"/><OM:OMI>1</OM:OMI><OM:OMI>2</OM:OMI></OM:OMA>
>>>
## Now we can reuse the variable A in other computations 
>>>
>>> cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("list2", "size", A))));
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMI>2</OM:OMI></OM:OMA></OM:OMATTR></OM:OMOBJ>
<xmlNode (OMOBJ) object at 0xea7290>
>>> 
===============================================================================
 
Finally, since kapy is written in python, it is natural to be able 
to convert basic OM objects like OMI, OMF, OMSTR and complex OM structures
to their python representation or into a record using the function named 
PyConvert. The object to be converted should be a complete OpenMath 
object e.g with the attribute option.

Example 4:
---------

===============================================================================
>>> B=cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "123.omsymcom:lesseni:26134", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.omi(256))))
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>123.omsymcom:lesseni:26134</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMI>256</OM:OMI></OM:OMA></OM:OMATTR></OM:OMOBJ>
>>> kapy.PyConvert(B);
256
>>>    
>>>
>>> C=cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("list1", "list", 1, kapy.oma("list1", "list", kapy.oma("complex1", "complex_cartesian", 7, 8), "I am a string"), 2, 9.5))));
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMA><OM:OMS cd="list1" name="list"/><OM:OMI>1</OM:OMI><OM:OMA><OM:OMS cd="list1" name="list"/><OM:OMA><OM:OMS cd="complex1" name="complex_cartesian"/><OM:OMF dec="7.0000000000000000000E+0000000"/><OM:OMF dec="8.0000000000000000000E+0000000"/></OM:OMA><OM:OMSTR>I am a string</OM:OMSTR></OM:OMA><OM:OMI>2</OM:OMI><OM:OMF dec="9.5000000000000000000E+0000000"/></OM:OMA></OM:OMA></OM:OMATTR></OM:OMOBJ>
>>>
>>> kapy.PyConvert(C);
[1, [(7+8j), 'I am a string'], 2, 9.5]

>>>
>>>
>>> D=kapy.oma("arith1", "minus", kapy.oma("arith1", "power", 2, 127), 1);
>>> E=kapy.oma("integer2", "euler", D);
>>> F=kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", E));
>>> print F;
<OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR><OM:OMS cd="scscp1" name="option_return_object"/><OM:OMSTR> </OM:OMSTR></OM:OMATP><OM:OMA><OMS cd="scscp1" name="procedure_call"/><OM:OMA><OMS cd="integer2" name="euler"/><OM:OMA><OMS cd="arith1" name="minus"/><OM:OMA><OMS cd="arith1" name="power"/><OM:OMI>2</OM:OMI><OM:OMI>127</OM:OMI></OM:OMA><OM:OMI>1</OM:OMI></OM:OMA></OM:OMA></OM:OMA></OM:OMATTR>
>>>
>>> G=cas.compute(F);
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMI>170141183460469231731687303715884105726</OM:OMI></OM:OMA></OM:OMATTR></OM:OMOBJ>
>>>
>>> kapy.PyConvert(G);
170141183460469231731687303715884105726L
>>>
>>>

Other computation by using an intermediate computation:
------------------------------------------------------- 
>>> H=cas.compute_intermediate(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id", "123.sylla:125:symcomp",kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("arith1", "minus", kapy.oma("arith1", "power", 2, 127), 1))));
<OM:OMI>170141183460469231731687303715884105727</OM:OMI>
>>>
>>>
>>> I=cas.compute(kapy.omattr(kapy.omatp(kapy.oms("scscp1", "call_id"), "1238.sylla:125:symcomp", kapy.oms("scscp1", "option_return_object"), " "), kapy.oma("scscp1", "procedure_call", kapy.oma("integer2", "euler", H))));
<OM:OMOBJ xmlns:OM="http://www.openmath.org/OpenMath" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmath.org/OpenMath http://www.openmath.org/standard/om20-2004-06-30/openmath2.xsd" version="2.0"><OM:OMATTR><OM:OMATP><OM:OMS cd="scscp1" name="call_id"/><OM:OMSTR>1238.sylla:125:symcomp</OM:OMSTR></OM:OMATP><OM:OMA><OM:OMS cd="scscp1" name="procedure_completed"/><OM:OMI>170141183460469231731687303715884105726</OM:OMI></OM:OMA></OM:OMATTR></OM:OMOBJ>
>>>
>>> kapy.PyConvert(I);
170141183460469231731687303715884105726L
>>> 
===============================================================================

Note that we can also use kapy to create interactions between SCSCP servers.
In the case you use the KANT SCSCP server to interact with other SCSCP servers,
you should run it with the -z option to dispatch the OpenMath objects without
namespace. Also you should replace the both following lines in the kapy script
(kapy.py):

the line pysh_ns = pysh_dummy.newNs("http://www.openmath.org/OpenMath", "OM");
by pysh_ns = pysh_dummy.newNs("http://www.openmath.org/OpenMath", None);

the line omobj.newNs("http://www.openmath.org/OpenMath", "OM");
by omobj.newNs("http://www.openmath.org/OpenMath", None);

Once you replace the both lines in the kapy script forever, you should always 
run the KANT SCSCP server with the -z option.
You can find more informatioins in the documentation in PDF format at
http://www.math.tu-berlin.de/~kant/kantscscp.html



Have a lot of fun -)