SWire documentation

About SWire

SWire is a software interface, enabling us to query Stata for the executing of basic operations, such as reading or writing data. The core of SWire is a Stata-Java plugin which functions as a server; it can be queried by using the HTTP protocol. Clients, such as a desktop software application or a web page, can be developed for interacting with Stata, thus allowing the integration between Stata and other software.

SWire is in essence a wrapper around the Stata-Java API; all the functions relating to this API can, therefore, be externally called by clients. SWire exposes the Stata-Java API, together with other SWire special methods. Special methods are functions facilitating the interaction between Stata and external clients; they provide additional functionalities than those provided by the Stata-Java API.

SWire can be interrogated on a local network and it accepts AJAX queries. This allows for the development of web applications to provide the user with graphical user interfaces. For example, a web application running on a browser can interact with Stata on a local network; this application could be a data entry form or an automatic report.

By providing a communication protocol, SWire makes it possible to connect Stata with many other applications for data exchange and basic interaction, thereby extending the capabilities of Stata. SWire requires Stata >=13.

The SWire protocol is based on HTTP. The body of the HTTP request/response is a SWire request/response. The HTTP body is a base64 encoding of a MessagePack serialization of a JSON request/response. The SWire request/response syntax can be described by JSON strings. The SWire protocol documentation is described in the SWire project web site.

Installation

SWire must be installed in a valid Stata ado-directory. Here will be discussed how to install SWire in your personal ado-directory. You can find out your personal ado-directory by using the "personal" command in Stata. To do that, type this in Stata:

personal

Then, follow these instructions:

1. if your personal ado-directory does not exist, then create it;
2. copy swire.ado and swire.sthlp in your personal ado-directory;
3. copy the contents of the jar folder in the "jar" folder under you personal ado-directory. If the "jar" folder does not exist under you personal ado-directory, then create it first.

At the end of this process this will be the structure of your personal ado-directory (let suppose the your personal ado-directory is "/home/john/ado/personal/"):

/home/john/ado/personal/swire.ado
/home/john/ado/personal/swire.sthlp
/home/john/ado/personal/jar/swire.jar
/home/john/ado/personal/jar/lib/javassist-3.20.0-GA.jar
/home/john/ado/personal/jar/lib/msgpack-0.6.12.jar

Try this command in Stata:

swire version

The previous command will display the SWire version number if the installation was successful.

The swire Stata command

The swire Stata command is a wrapper aroud the SWire plugin. It is indeed a collection of Stata commands:

• swire
• swire start
• swire stop
• swire status
• swire methods

swire

Syntax

swire

Description

swire displays the list if the SWire commands, namely: swire start, swire stop, swire status, swire methods and swire version.

swire start

Syntax

swire start [, port(port_number)]

Description

swire start is the command for starting the SWire server. It accepts the optional argument port() for specifying the network port number on which the SWire server will listen. If port() is not specified, port 50000 will be used by default. A valid port number between 1024 and 65535 must be specified. The port must be not used by other applications and no firewall must block network traffic on that port. Other applications can interact with SWire only if the SWire server is listening.

swire stop

Syntax

swire stop

Description

swire stop is the command for stopping the SWire server.

swire status

Syntax

swire status

Description

swire status reports the status of the SWire server. The SWire server can listen or not listen on a network port.

Stored results

Macros
r(status)
The SWire server status

Scalars
r(port)
The network port number used by the SWire server (a missing value is returned if the SWire server is not listening)

swire methods

Syntax

swire methods

Description

swire methods displays the Stata-Java API methods and the SWire special methods that are exposed by SWire. A corresponding availability status is also reported for each Stata-Java API method. A Stata-Java API method is unavailable if the method is not available in the Stata-Java API, which is used by your Stata release.

swire version

Syntax

swire version

Description

swire version displays the SWire version number.

Stored results

Scalars
r(version)
The SWire version number.

Copyright

SWire is distributed with the following Java libraries:

• Javassist 3.20.0-GA
• msgpack-java 0.6.12

Javassist is released under the Mozilla Public License 1.1 (https://www.mozilla.org/en-US/MPL/1.1/).
Msgpack-java is released under the Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0).