Stata Plugins: the C-Sweet

I thought I’d take a quick break from the latest series on building the Twitter API Library to bring you a message sponsored by Stata Plugins!  Okay, we’re not officially sponsored by Stata and, legally speaking, we’re not sponsored by anyone.  Technicalities.  Maybe someday you’ll wish to plug your brand [here], but even I think that’s highly unlikely – so let’s just get right to plugins.

Do you know C?  I wouldn’t say I know it very well, but that sure as hell shouldn’t stop us – this is a great learning opportunity!  If you know the language, please feel free to skip to the next paragraph.  Still here?  Excellent!  That means you’re like me and aren’t too concerned with lower level programming languages (that’s code for a language that’s a lot more explicit – it doesn’t look like English anymore).  After all, a statement such as:

regress price mpg

​is much easier to understand than this great (albeit extremely technical) Stata Blog post showing us what’s actually going on behind the scenes so to speak.  Now, I actually have some training in Java, but honestly I have to tribute my smooth transition into C to Mata.  Mata is a wonderful extension to Stata and I highly recommend picking it up if you haven’t already.  It can be difficult to transition to Mata if you simply use Stata and there seems to be a lack of literature pertaining to learning Mata.  I’ll point you to UCLA’s code fragment on Mata or Bill Gould’s Mata Matters/Mata the Missing Manual resources if you wish to learn more.  The observation is: Mata prepares you for C because it’s extremely similar to the C language and a great transitional language from Stata to C.  What’s the point though, right?  Well, Mata enables you to be quicker and do complicated things directly from your do-file.  Learning C, while sometimes unnecessary if your job is strictly to do quick analysis, will make it so that you can blow your colleagues away by showing them how your new program reduced the return time of a command from .8 to .6 seconds.  Sorry again colleagues.

Troubleshooting is difficult and I hope to have a video available soon, but not today.   So what’s a practical application for plugins?  Directly related to the Twitter API posts, we need Stata to provide us with the time.  “That’s dumb” you’d say.  Just use - c(current_time) -.  Fine, but now we need time in UTC which by the way is combination of the acronyms Coordinate Universal Time (CUT) and the French Temps Universel Coordonné (TUC).  So how about:

clock(c(current_time) , "hms") – (TimeOffsetfromGMT)*60*60*1000

Close!  But we’re also extremely lazy and want the computer to figure out which time zone we’re in (regardless of whether we have internet connection or not) and it needs to work in batch mode!  Okay okay, enough with the requests!  Basically, the question is how can we take the computer’s internal UTC time information?  That’s where Stata plugins come in handy.

At a high level, what we’re going to do is tell Stata: “Hey Stata, go ahead and talk to the computer.  Ask it what the current UTC time is and place the result in a local macro that we can call later.  Thanks!”
​
Because I have a 64-bit system, it seems that the simple things tend to get a little complicated.  I compile the file in Visual Studio (x64) and I also have the 64-bit version of Stata installed.  Here’s the main file st_utc.c which should be compiled with the two necessary Stata files stplugin.c and stplugin.h.  In other words, it worked for me but unfortunately I give no guarantees that it will work seamlessly on your end.  Please edit as necessary.

So what’s going on here?  Well, the beauty of this file is that we can load whatever libraries we need – here we included the time library so that we can access time variables directly from our stata_call routine.  Note how we declare our error handling variable to be of type ST_retcode.  We are able to call SF_display which prints the contents of a variable or string to the Stata console and SF_macro_save which allows us to access the contents of the variable buf (our time string) directly from the Stata local `utc_time’ thanks to the stplugin.h header. 
 
After compiling st_utc.dll, you can either rename it st_utc.plugin and place it in your personal ado directory for easy access, or keep it as a dll and specify the location of the file using the option using() as shown below:

program st_utc, plugin using(st_utc.dll)
plugin call st_utc

And it’s that easy!  Or so it seems.  There are a lot of technical errors that you have to keep in mind from operating systems, to Stata versions (look to older plugin interface versions with older versions of Stata), to whether you really want to spend the time debugging your compiled code.  It’s well worth getting it to work at least once!  The important take away here is that any Stata user can greatly extend the capabilities of Stata; we haven’t even talked about javacall yet.  So the next time a non-Stata user tries to assert their software package dominance by saying: “oh, Stata couldn’t do “x” so I had to use some otheR package”, bet them $20 they’re wrong.  Most of the time, they don’t know what they’re talking about and you’ll have $20 to spend on some sweet Stata swag (seriously, we’re not sponsored by Stata).