#############################################################################
##
#W openmath.gd The SCSCP package Olexandr Konovalov
#W Steve Linton
##
#############################################################################
###########################################################################
##
## OMGetObjectWithAttributes
##
## <#GAPDoc Label="OMGetObjectWithAttributes">
##
## <ManSection>
## <Func Name="OMGetObjectWithAttributes" Arg="stream" />
## <Returns>
## record with components <C>object</C> and <C>attributes</C>, or <K>fail</K>
## </Returns>
## <Description>
## <!-- TODO: Document option return_tree -->
## This function is similar to the function <C>OMGetObject</C> from the
## &OpenMath; package, and the main difference is that it is able to
## understand &OpenMath; attribution pairs. It retrieves exactly one
## &OpenMath; object from the stream <A>stream</A>, and stores it in the
## <C>object</C> component of the returned record. If the &OpenMath; object
## has no attributes, the <C>attributes</C> component of the returned record
## will be an empty list, otherwise it will contain pairs
## <C>[attribute&uscore;name,attribute&uscore;value]</C>, where
## <C>attribute&uscore;name</C> is a string, and <C>attribute&uscore;value</C>
## is a &GAP; object, whose type is determined by the kind of an attribute.
## Only attributes, defined by the SCSCP are allowed, otherwise an error
## message will be displayed. <P/> If the procedure was not successful, the
## function returns <K>fail</K> instead of an error message like the function
## <Ref BookName="OpenMath" Func="OMGetObject" /> does. Returning <K>fail</K>
## is useful when <C>OMGetObjectWithAttributes</C> is used inside
## accept-evaluate-return loop.
## <P/>
## As an example, the file <File>scscp/tst/omdemo.om</File> contains some
## &OpenMath; objects, including those from the SCSCP Specification
## <Cite Key="SCSCP"/>. We can retrieve them from this file,
## preliminary installing some SCSCP procedures
## using the function <Ref Func="InstallSCSCPprocedure"/>:
## <Example>
## <![CDATA[
## gap> InstallSCSCPprocedure("WS_Factorial", Factorial );
## gap> InstallSCSCPprocedure("GroupIdentificationService", IdGroup );
## gap> InstallSCSCPprocedure("GroupByIdNumber", SmallGroup );
## gap> InstallSCSCPprocedure( "Length", Length, 1, 1 );
## gap> test:=Filename( Directory( Concatenation(
## > GAPInfo.PackagesInfo.("scscp")[1].InstallationPath,"/tst/" ) ),
## > "omdemo.om" );;
## gap> stream:=InputTextFile(test);;
## gap> OMGetObjectWithAttributes(stream);
## rec(
## attributes := [ [ "option_return_object", "" ], [ "call_id", "5rc6rtG62" ] ]
## , object := 6 )
## gap> OMGetObjectWithAttributes(stream);
## rec( attributes := [ ], object := 1 )
## gap> OMGetObjectWithAttributes(stream);
## rec( attributes := [ ], object := 120 )
## gap> OMGetObjectWithAttributes(stream);
## rec(
## attributes := [ [ "call_id", "alexk_9053" ], [ "option_runtime", 300000 ],
## [ "option_min_memory", 40964 ], [ "option_max_memory", 134217728 ],
## [ "option_debuglevel", 2 ], [ "option_return_object", "" ] ],
## object := [ 24, 12 ] )
## gap> OMGetObjectWithAttributes(stream);
## rec(
## attributes := [ [ "call_id", "alexk_9053" ], [ "option_return_cookie", "" ]
## ], object := <pc group of size 24 with 4 generators> )
## gap> OMGetObjectWithAttributes(stream);
## rec( attributes := [ [ "call_id", "alexk_9053" ], [ "info_runtime", 1234 ],
## [ "info_memory", 134217728 ] ], object := [ 24, 12 ] )
## gap> CloseStream( stream );
## ]]>
## </Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "OMGetObjectWithAttributes" );
DeclareGlobalFunction( "OMgetObjectXMLTreeWithAttributes" );
###########################################################################
##
## OMPutProcedureCall( <stream>, <proc_name>, <objrec> )
##
## <#GAPDoc Label="OMPutProcedureCall">
##
## <ManSection>
## <Func Name="OMPutProcedureCall" Arg="stream proc_name objrec" />
## <Returns>
## nothing
## </Returns>
## <Description>
## Takes a stream <A>stream</A>, the string <A>proc&uscore;name</A> and a
## record <A>objrec</A>, and writes to <A>stream</A> an &OpenMath; object
## <C>procedure&uscore;call</C> for the procedure <A>proc&uscore;name</A> with
## arguments given by the list <C>objrec.object</C> and procedure call options
## (which should be encoded as &OpenMath; attributes) given in the list
## <C>objrec.attributes</C>.
## <P/>
## This function accepts options <C>cd</C> and <C>debuglevel</C>.
## <P/>
## <C>cd:="cdname"</C> may be used to specify the name of the content
## dictionary if the procedure is actually a standard &OpenMath; symbol.
## Note that the server may reject such a call if it accepts only calls
## of procedures from the transient content dictionary, see
## <Ref Func="InstallSCSCPprocedure"/> for explanation). If the <C>cdname</C>
## is not specified, <C>scscp_transient_1</C> content dictionary will be
## assumed by default.
## The value of the <C>debuglevel</C> option is an integer. If it is non-zero,
## the <C>procedure&uscore;completed</C> message will carry on also some
## additional information about the call, for example, runtime and memory
## used.
## <!-- TODO: document debuglevel option in more details -->
## <Example>
## <![CDATA[
## gap> t:="";; stream:=OutputTextString(t,true);;
## gap> OMPutProcedureCall( stream, "WS_Factorial", rec( object:= [ 5 ],
## > attributes:=[ [ "call_id", "user007" ],
## > ["option_runtime",1000],
## > ["option_min_memory",1024],
## > ["option_max_memory",2048],
## > ["option_debuglevel",1],
## > ["option_return_object"] ] ) );;
## gap> Print(t);
## <?scscp start ?>
## <OMOBJ xmlns="
http://www.openmath.org/OpenMath" version="2.0">
## <OMATTR>
## <OMATP>
## <OMS cd="scscp1" name="call_id"/>
## <OMSTR>user007</OMSTR>
## <OMS cd="scscp1" name="option_runtime"/>
## <OMI>1000</OMI>
## <OMS cd="scscp1" name="option_min_memory"/>
## <OMI>1024</OMI>
## <OMS cd="scscp1" name="option_max_memory"/>
## <OMI>2048</OMI>
## <OMS cd="scscp1" name="option_debuglevel"/>
## <OMI>1</OMI>
## <OMS cd="scscp1" name="option_return_object"/>
## <OMSTR></OMSTR>
## </OMATP>
## <OMA>
## <OMS cd="scscp1" name="procedure_call"/>
## <OMA>
## <OMS cd="scscp_transient_1" name="WS_Factorial"/>
## <OMI>5</OMI>
## </OMA>
## </OMA>
## </OMATTR>
## </OMOBJ>
## <?scscp end ?>
## ]]>
## </Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "OMPutProcedureCall" );
###########################################################################
##
## OMPutProcedureCompleted
##
## <#GAPDoc Label="OMPutProcedureCompleted">
##
## <ManSection>
## <Func Name="OMPutProcedureCompleted" Arg="stream objrec"/>
## <Returns>
## <K>true</K>
## </Returns>
## <Description>
## Takes a stream <A>stream</A>, and a record
## <A>objrec</A>, and writes to <A>stream</A> an &OpenMath; object
## <C>procedure&uscore;completed</C>
## with the result being <C>objrec.object</C> and information messages
## (as &OpenMath; attributes) given in the list <C>objrec.attributes</C>.
## <Example>
## <![CDATA[
## gap> t:="";; stream:=OutputTextString(t,true);;
## gap> OMPutProcedureCompleted( stream,
## > rec(object:=120,
## > attributes:=[ [ "call_id", "user007" ] ] ) );
## true
## gap> Print(t);
## <?scscp start ?>
## <OMOBJ xmlns="
http://www.openmath.org/OpenMath" version="2.0">
## <OMATTR>
## <OMATP>
## <OMS cd="scscp1" name="call_id"/>
## <OMSTR>user007</OMSTR>
## </OMATP>
## <OMA>
## <OMS cd="scscp1" name="procedure_completed"/>
## <OMI>120</OMI>
## </OMA>
## </OMATTR>
## </OMOBJ>
## <?scscp end ?>
## ]]>
## </Example>
## </Description>
## </ManSection>
## <#/GAPDoc>
DeclareGlobalFunction( "OMPutProcedureCompleted" );
###########################################################################
##
## OMPutProcedureTerminated
##
## <#GAPDoc Label="OMPutProcedureTerminated">
##
## <ManSection>
## <Func Name="OMPutProcedureTerminated" Arg="stream objrec error_cd error_type"/>
## <Returns>
## nothing
## </Returns>
## <Description>
## Takes a stream <A>stream</A>, and a record with an error message
## <A>objrec</A> (for example <C>rec( attributes := [ [ "call_id",
## "localhost:26133:87643:gcX33cCf" ] ],</C> <C>object := "localhost:26133
## reports : Rational operations: <divisor> must not be zero")</C> and
## writes to the <A>stream</A> an &OpenMath; object
## <C>procedure&uscore;terminated</C> containing an error determined by the
## symbol <A>error_type</A> from the content dictionary <A>error_cd</A> (for
## example, <C>error_memory</C>, <C>error_runtime</C> or
## <C>error_system_specific</C> from the &scscp1; content dictionary (<Cite
## Key="scscp1cd"/>). <P/> This is the internal function of the package which
## is used only in the code for the &SCSCP; server to return the error message
## to the client.
## </Description>
## </ManSection>
## <#/GAPDoc>
DeclareGlobalFunction( "OMPutProcedureTerminated" );
###########################################################################
##
#E
##
