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

• If your personal ado-directory does not exist, then create it;
• Copy swire.ado and swire.sthlp in your personal ado-directory;
• 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 displays the list if the SWire commands, namely: swire start, swire stop, swire status, swire methods and swire version.

swire stop

Syntax

swire stop

Description

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

swire status

Syntax

swire status

Description

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

swire methods

Syntax

swire methods

Description

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

swire version

Syntax

swire version

Description

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