Appearance

SERVICE ​

Starts or stops the ADOxx Web Service server.

Syntax ​

Starting the server:

leo-grammar
CC "AdoScript" SERVICE start [ port:intValue ] [ backlog:intValue ]
    [ logformat: short | long ]
    [ output: statusbar | textfield ] .

# --> RESULT ecode:intValue .

Stopping the server:

leo-grammar
CC "AdoScript" SERVICE stop .

# --> RESULT ecode:intValue .

Parameters ​

Parameters for starting the server:

  • start (modifier) - Starts the ADOxx Web Service server.
  • port (intValue, optional) - The port at which the ADOxx Web Service server receives requests. Default is 80.
  • backlog (intValue, optional) - The max queue size for requests. Default is 100.
  • logformat (enumValue, optional) - Specifies the log format, which is however not directly shown to the user. Default is short.
  • output (enumValue, optional) - Specifies where the status messages of the ADOxx Web Service server are written. Default is statusbar.

Parameters for stopping the server:

  • stop (modifier) - ends the ADOxx Web Service server.

Returns ​

  • ecode (intValue) - Contains the error code or 0 in case of success.

Details ​

If started, ADOxx opens a port where SOAP messages can be sent through an HTTP POST request. The SOAP message must contain an AdoScript, which is then executed in the current ADOxx instance.

The SOAP message sent to the ADOxx server should look something like:

xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adows="urn:AdoWS">
  <soap:Body>
    <adows:execute soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <script xsi:type="xsd:string">
<!-- Enter AdoScript code to execute here. -->
      </script>
      <resultVar xsi:type="xsd:string"><!-- Enter name of variable to return here. --></resultVar>
    </adows:execute>
  </soap:Body>
</soap:Envelope>

The response provided by the server is then:

xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:adows="urn:AdoWS">
    <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <adows:ExecuteResponse>
            <errorCode>0</errorCode> <!-- This is NOT the value of the ecode variable! -->
            <result><!-- The value of the variable specified for `resultVar` in the request. --></result>
        </adows:ExecuteResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

To return complex results build an array or a map as part of the script sent to the server and return it as the value.

When statusbar is specified for the output parameter then the messages are shown in the status bar. Using textfield instead will create an output window with the ID "AdoScriptService" (see "AdoScript" CREATE_OUTPUT_WIN for details) and append the messages to a textfield. Appending the messages to a textfield reduces the server performance (compared to statusbar mode), so it should only be used when really needed.

Problems can occur if the server executes AdoScript at the same time as the user interface is changed through user interaction. Therefore, it is recommend to block the user interaction, for example thorough the "AdoScript" MSGWIN command. Furthermore, calling commands from the "Modeling" MessagePort can cause the user interface to freeze.

For more information see the ADOxx Web Service page.

See Also ​

MSGWIN

Examples ​

Start the server with:

asc
CC "AdoScript" SERVICE start port:59001

This starts the server on port 59001 and puts the output in the statusbar (on the bottom of the GUI).

Then from the same computer send an HTTP POST request to http://localhost:59001 using an application of your choice (like Burno or Postman) with the following body:

xml
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adows="urn:AdoWS">
  <soap:Body>
    <adows:execute soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <script xsi:type="xsd:string">
CC "AdoScript" MSGWIN ("Working the magic...")
SETL nTemp:(2+3)
CC "AdoScript" MSGWIN hide
      </script>
      <resultVar xsi:type="xsd:string">nTemp</resultVar>
    </adows:execute>
  </soap:Body>
</soap:Envelope>

The received response should looks something like:

xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:adows="urn:AdoWS">
    <SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <adows:ExecuteResponse>
            <errorCode>0</errorCode>
            <result>5</result>
        </adows:ExecuteResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Once done experimenting, stop the server with:

asc
CC "AdoScript" SERVICE stop

Versions and Changes ​

Available since ADOxx 1.3