TMlib User Guide

Data in the TMlib model is organized in an inverted tree structure, much like the structure of the filesystem on a modern operating system. The user first needs to know the Mission for which they would like to retrieve data. Next, in the case of the STEREO mission, there are two Spacecraft, as such, the user must select one. After selecting the spacecraft, an Instrument on the spacecraft must be selected to gather events from. In our example below we've chosen the SWAVES instrument. Finally, after choosing the instrument, the user selects an EventType. Each EventType has its own unique set of items that it contains, though all items from event levels above the chosen one are also valid for the current EventType. For example, an LFR EventType would contain all items specific to itself along with any items that are valid for any upper levels, such as CCSDS items which are valid for all EventTypes. See the online help system for a better understanding of what this means.

When connecting to the TMlib server a user needs to specify the Mission, the Spacecraft, the Instrument, and the EventType to the library. This quadruple is called the MSIE domain. The MSIE domain is used to specify a set of data the user is interested in getting as mentioned above. For example, if a user wanted to see every packet coming from the spacecraft, they would specify an MSIE domain such as this:

/* Example in C */
/*                             Mission       Spacecraft      Instrument      EventType */
TM_Select_Domain(&stream_id,   "stereo",     "stereo_a",      "swaves",      "packet");

The stream_id variable in the above code fragment is a unique identifier or handle that TMlib returns to the user program for use in subsequent TMlib function calls, it is explained in the detailed API documentation in this book. The use of a session identifier allows a user program to have multiple open connections to the server simultaneously.

After specifying the MSIE, the user has to specify a stream. A stream is a data source; a place from which the user would like to get data. For example, the stream could be the realtime stream coming from the spacecraft, it could be a path to a file on a TMlib server containing a particular day's worth of recorded data, or it could be the chooser. Though the chooser is not technically a stream, it opens a file browser that allows the user to select a stream. The chooser is described in the following sections. Some examples of selecting a stream:

; Example in IDL
TM_Select_Stream_File(stream_id, 'realtime')
; or
TM_Select_Stream_File(stream_id, '+/path/to/file/on/server') ; note the preceding plus '+' sign
; or
TM_Select_Stream_File(stream_id, 'chooser')
; or
TM_Select_Stream_Timerange(stream_id, startUR8, endUR8)

After the domain and the stream have been specified, the user calls the event function and waits for the requested event to be built, for example:

// Example in Java
import edu.space.umn.swaves.*;

...

for (;;) {
    TM.TM_Find_Event(stream_id);

    ...
}

The TM_Find_Event function will block and wait for the event to be built on the server. After the event is complete, the server will notify the client and the function will return. The user can then call any of the TM_Get_Item functions appropriate for the EventTypes they have requested. Complete examples are located in Section 5, though here is a quick example to illustrate this point:

/* Example in C */
#define ITEM_BUFFER_SIZE 1

int number_of_returned_elements, item_buffer[ITEM_BUFFER_SIZE];

...

TM_Get_Item_I4(stream_id, "CCSDS_APID", item_buffer, ITEM_BUFFER_SIZE, &number_of_returned_elements);

printf("APID: %d\n", item_buffer);

...

In the above code snippet, we ask the server for the CCSDS_APID item (from the "/stereo/stereo_a/swaves/packet" MSIE). We know that the item we have requested, CCSDS_APID, is a scalar of size 1 (that is, one "I4" [or four 8bit bytes]), so item_buffer only needs to be of size 1. Also note that the number of elements in the returned array is stored in the variable number_of_returned_elements. By the way, if we expected a vector back from TMlib but had not given it enough storage in the array we passed in, the TM_Get_Item_I4 function would return a fatal (negative) error stating that the server returned more data than space available in the array. The contents of the array passed into the function would be invalid and of course should not be used.

As noted above, the chooser is an application embedded in TMlib. It allows the user to easily browse through the file directory hierarchy on the server and choose data files, or from the realtime stream if so desired.

2.1.3.1. Mac OS X

When a user specifies "chooser" for the stream argument to TM_Select_Stream, a small application embedded into the TMlib client will open in the current terminal session. From here the user can navigate the directory hierarchy to find the file containing the data they are interested in. The screenshot below is of the root level. The user can also press the 'L' key to automatically select the last data file or stream selected. You can see the shortcut in the bottom of the screenshot below.

Figure 1. Root level of the Mac OS X curses-based chooser

Navigating via the arrow keys to "DATA" and pressing enter, you will find the hierarchy starting with the mission. Also note that in any screenshots below the chooser root level, there is an item called "..". Selecting this item will bring the user back to the previous level, functioning identically to a parent directory.

After navigating to the level containing the data files or stream desired, use the arrow keys to move to the file to select it and press enter. This will close the chooser window and tell the server to start streaming the data from this file to the user's application. From this point on, control is given back to the user's application. A screenshot of selecting a file is included below.

Figure 2. Selecting a data file in the chooser.

The file selected will be saved in the .tmlibrc file in the user's home directory in case the user would like the invoke the "Last Stream" command (the 'L' key) at the chooser's root level. In this case we are about to select SWAVES_EMA_2005_084_220652.PTPDAQ. We found this file by descending down through "DATA"->"STEREO"->"STEREO_A"->"SWAVES".

Note

The filename itself has valuable information encoded into it. Starting from the left, and delimited by the underscore character, the filename contains the instrument name, the spacecraft name, the year, the day of year, and the time (UTC).

2.1.3.2. Windows XP

The Windows based chooser functions exactly the same way the Mac OS chooser functions with the exception that instead of a terminal-based application taking over a console window, a normal window will open up a screen much like that of the chooser on Mac OS X. The user can navigate the chooser by double-clicking. A screenshot of the Windows chooser at its root level is located below.

Figure 3. Windows chooser

Under the Windows chooser, the "Last Stream Chosen" functionality is implemented by the "Last Stream Chosen" item in the files pane of the Windows chooser. Below is a screenshot of a user selecting a data file to be read.

Figure 4. Selecting a file via the Windows chooser

Again notice the presence of the "../" item in the above screenshot. As in Mac OS X, this item serves to bring the user back to the previous level if selected.

The table below lists all the functions that comprise the item retrieval portion of TMlib. The exact signatures of these functions are listed in a later section. For now, these tables are a brief introduction and reference to the TMlib API.

In addition to the aforementioned item retrieval functions, there are a host of convenience functions that handle dates and times and the conversions between them. The table below lists all of these remaining functions. Again, the exact signatures of these functions are described in Section 4.2.

TMlib is distributed in PackageMaker form for Mac OS X. Installation is straight forward and consists of running the package installer and following the prompts. After the package installer completes, the TMlib library will be installed in the /Applications/STEREO/TMlib_Client folder of your main hard drive. In that directory you will find example code, startup files, utility programs, documentation, and the client libraries themselves.

As part of the installation process, the installer will modify your .cshrc and/or .bash_profile scripts to execute a startup file located in the TMlib installation directory called TMlib_Startup.sh or TMlib_Startup.csh depending on which shell you use. This file initializes some environment variables which are described below.

After installation has completed you should log out and log back in again to allow the environment variables to be set correctly. Advanced users could also do this by hand by manually sourcing their shell initialization scripts.

TMlib for Windows is distributed in MSI package form.

Like Mac OS X, installation on the Windows platform is very straight forward. Run the installer and follow the prompts. If you've installed TMlib in the default directory it will be located in C:\Program Files\STEREO\TMlib_Client. Again, under that directory is where you will find all the examples, client utilities, etc.

Under Windows, all the same environment variables are set as they are in Mac OS X except of course that there is no shell script to set them. Instead, all of the environment variables have user scope and are set via the standard Windows mechanism which is described below.

After installation has completed you should log out and log back in again to allow the environment variables to be set correctly.

As noted in the table below, STEREO_TMlib_Client_Home is the only TMlib client specific environment variable. The rest of the variables listed are development environment specific.

The TMlib client now has a new way to configure and specify parameters called tmconfig that replaces the old (and deprecated) environment variable method.

tmconfig is a command line utility that can be used to maintain what are called "sites". Within each site is contained a set of parameters that can uniquely identify a site. Parameters such as server name or IP, server port number, last file chosen in the chooser, and what the current default site are all available via this command. For example, to list all the available sites you use the -l (ell) option:

unix_or_windows$ tmconfig -l
RT TMserver A at UMN           128.101.218.170 
RT TMserver A at APL           128.244.181.238 
RT TMserver B at APL           128.244.181.239 
RT TMserver at Meudon          145.238.10.253  
TMserver at GSFC               128.183.134.187 
TMserver at UCB                128.32.147.148  
localhost                      127.0.0.1       (DEFAULT)

Notice how the listing provides the symbolic name of the server and its IP address. Also note the item marked as "DEFAULT". This is the site that would be used for any TMlib client programs, it functions like with the old STEREO_Server environment variable. To select another site for use, the -d and -s options are utilized:

unix_or_windows$ tmconfig -d -s umn
unix_or_windows$ tmconfig -l
RT TMserver A at UMN           128.101.218.170 (DEFAULT)
RT TMserver A at APL           128.244.181.238 
RT TMserver B at APL           128.244.181.239 
RT TMserver at Meudon          145.238.10.253  
TMserver at GSFC               128.183.134.187 
TMserver at UCB                128.32.147.148  
localhost                      127.0.0.1 

Note how only a few characters of the site name we wanted to become default were specified. In this way, descriptive names can be used, but the user is not required to type the entire site name to specify it, only a few unique characters need be used.

Sites can be added, modified, and deleted via the command-line utility or by manually modifying the configuration file itself. If modifying the configuration file manually, care must be taken to maintain a valid XML document. The file is located in the user's home directory on Unix-like platforms and is named .tmlibrc or on the Windows platform it is located in the STEREO_TMlib_Client_Home directory and is named tmlibrc. Comments are provided in the configuration file itself on what all the valid XML elements are and how they are used. An example configuration file is listed below:

Modifying the file via the command line utility tmconfig is relatively straightforward as well and can be accomplished by reading the command help which is available via the -h option:

unix_or_windows$ tmconfig -h
usage: tmconfig [-d|-l|-c|-a|-r|-m {key=value}] [-s {sitename}]

Only one command at a time may be issued. Enclose parameters containing 
spaces in quotes.

Commands:
-d              Set a site to be the default site. Requires -s
-l              List all available sites.
-c              Create a new configuration file. OVERWRITES EXISTING FILE!!!
-a              Add a site. Requires -s
-r              Remove a site. Requires -s
-m key=value    Modify specfied key=value pair. Without -s, operates on DEFAULT
                site. Valid keys are: NAME, SERVER, LASTFILE, and PORT

Options:
-s sitename     Specify site name. 

The normal steps in creating a site consist of adding a site and then modifying the appropriate key/value pairs to tailor it to personal preferences.

Open Terminal.app (this application is located under /Applications/Utilities) and type packets. If everything is installed correctly, after a short delay you should start seeing output of this form:

Figure 5. packets output

The packets program also supports the "-c" option which will bring up the chooser and allow you to choose a stream other than realtime, which packets uses by default. This can be useful if you are not connected to a server with a realtime data stream as would be the case after spacecraft launch.

Under Windows the steps are almost identical. Open up a Command window but going to Start->Run, type cmd, and click Run. Then type packets and you should see output that is almost identical to the image above. As under Mac OS X, the packets program supports the "-c" option for bringing up the chooser and selecting a stream.

Description: Selects the MSIE. Called first when setting up a connection.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Select_Domain(uint32_t *stream_id, char *mission, char *spacecraft, char *instrument, char *event);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Select_Domain(IntBuffer stream_id, String mission, String spacecraft, String instrument, String event);

; IDL

LONG TM_Select_Domain(LONG stream_id, STRING mission, STRING spacecraft, STRING instrument, STRING event)

Description: Selects the data source. Called after the MSIE has been selected.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Select_Stream_File(uint32_t streamid, char *stream);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Select_Stream_File(int streamid, String stream);

; IDL

LONG TM_Select_Stream_File(LONG streamid, STRING stream);

Description: Selects the data source designated by a start and end time. Called after the MSIE has been selected. Useful when data sets are large or events cross into the next day's worth of data. A startUR8 that is -1 means Beginning of Information (BOI). An endUR8 that is zero means End of Day (EOD) and an endUR8 that is -1 means End of Information (EOI).

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Select_Stream_TimeRange(uint32_t streamid, double startUR8, double endUR8);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Select_Stream_TimeRange(int streamid, double startUR8, double endUR8);

; IDL

LONG TM_Select_Stream_TimeRange(LONG streamid, DOUBLE startUR8, DOUBLE endUR8);

Description: Blocks until an event is built on the server. Called after selecting a stream.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Find_Event(uint32_t streamid);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Find_Event(int streamid);

; IDL

LONG TM_Find_Event(LONG streamid)

Description: Gets a specified item from the server as a 32bit integer scalar/vector. Called after an event is built.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Get_Item_I4(uint32_t streamid, char *item_name, int32_t *dest_buff, int32_t size_of_dest_buff, int32_t *num_of_ret_elements);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Get_Item_I4(int streamid, String item_name, IntBuffer dest_buff, int size_of_dest_buff, IntBuffer num_of_ret_elements);

; IDL

LONG TM_Get_Item_I4(LONG streamid, STRING item_name, LONG dest_buff, LONG size_of_dest_buff, LONG num_of_ret_elements)

Description: Gets a specified item from the server as a 32bit floating point scalar/vector. Called after an event is built.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Get_Item_R4(uint32_t streamid, char *item_name, float *dest_buff, int32_t size_of_dest_buff, int32_t *num_of_ret_elements);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Get_Item_R4(int streamid, String item_name, FloatBuffer dest_buff, int size_of_dest_buff, IntBuffer num_of_ret_elements);

; IDL

LONG TM_Get_Item_R4(LONG streamid, STRING item_name, FLOAT dest_buff, LONG size_of_dest_buff, LONG num_of_ret_elements)

Description: Gets a specified item from the server as a 64bit floating point scalar/vector. Called after an event is built.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Get_Item_R8(uint32_t streamid, char *item_name, double *dest_buff, int32_t size_of_dest_buff, int32_t *num_of_ret_elements);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Get_Item_R8(int streamid, String item_name, DoubleBuffer dest_buff, int size_of_dest_buff, IntBuffer num_of_ret_elements);

; IDL

LONG TM_Get_Item_R8(LONG streamid, STRING item_name, DOUBLE dest_buff, LONG size_of_dest_buff, LONG num_of_ret_elements)

Description: Gets a specified item from the server as a 8bit character scalar/vector. Called after an event is built. Normally used for retrieving strings from the server.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Get_Item_Char(uint32_t streamid, char *item_name, char *dest_buff, int32_t size_of_dest_buff, int32_t *num_of_ret_chars);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Get_Item_Char(int streamid, String item_name, CharBuffer dest_buff, int size_of_dest_buff, IntBuffer num_of_ret_chars);

; IDL

LONG TM_Get_Item_Char(LONG streamid, STRING item_name, BYTE dest_buff, LONG size_of_dest_buff, LONG num_of_ret_chars)

Description: Gracefully shuts the connection down between the server and the client. Always recommended for shutting down connections as it reduces the load on the TMlib server.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Close(uint32_t streamid);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Close(int streamid);

; IDL

LONG TM_Close(LONG streamid)

Description: Programmatically and temporarily overrides the value of the server parameter for the currently selected site.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Select_Server(char *server_name_or_ip);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Select_Server(String server_name_or_ip);

; IDL

LONG TM_Select_Server(STRING server_name_or_ip)

Description: Programmatically and temporarily overrides the value of the port parameter for the currently selected site.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Select_Port(int port);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Select_Port(int port);

; IDL

LONG TM_Select_Port(LONG port)

Description: Based on the string argument, this function returns a description of the last error that occured.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Error_Stack(uint32_t stream_id, char *description_type, char *dest_buff, int32_t size_of_dest_buff, int32_t *sizeof_ret_results);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Error_Stack(int stream_id, String description_type, CharBuffer dest_buff, int size_of_dest_buff, IntBuffer sizeof_ret_results);

; IDL

LONG TM_Error_Stack(LONG stream_id, STRING description_type, BYTE dest_buff, LONG size_of_dest_buff, LONG sizeof_ret_results)

Description: Sets the position in the stream via a time value in UR8 format. A UR8 that is zero means the Beginning of Range (BOR).

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Set_Position(uint32_t stream_id, double UR8);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Set_Position(int stream_id, double UR8);

; IDL

LONG TM_Set_Position(LONG stream_id, DOUBLE UR8)

Description: Gets the position in the stream as a time value in UR8 format.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int32_t TM_Get_Position(uint32_t stream_id, double *UR8);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_Get_Position(int stream_id, DoubleBuffer UR8);

; IDL

LONG TM_Get_Position(LONG stream_id, DOUBLE UR8)

Description: Convert a string of the exact form "07-Jan-1999:18:00:10.627" to a UR8.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_from_String_Absolute(double *UR8, char *date_string);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_from_String_Absolute(DoubleBuffer UR8, String date_string);

; IDL

LONG TM_UR8_from_String_Absolute(DOUBLE UR8, STRING date_string)

Description: Convert a UR8 to a string containing a date of the form "07-Jan-1999:18:00:10.627".

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_String_Absolute(double UR8, char *date_string);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_String_Absolute(double UR8, CharBuffer date_string);

; IDL

LONG TM_UR8_to_String_Absolute(DOUBLE UR8, BYTE date_string)

Description: Convert a string of the exact form "1983-09-18 11:42:25.056" to a UR8.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_from_String_Comparison(double *UR8, char *date_string);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_from_String_Comparison(DoubleBuffer UR8, String date_string);

; IDL

LONG TM_UR8_from_String_Comparison(DOUBLE UR8, STRING date_string)

Description: Convert a UR8 to a string containing a date of the exact form "1983-09-18 11:42:25.056".

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_String_Comparison(double UR8, char *date_string);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_String_Comparison(double UR8, CharBuffer date_string);

; IDL

LONG TM_UR8_to_String_Comparison(DOUBLE UR8, BYTE date_string)

Description: Convert a UR8 to a LOCALIZED (if set) string containing a date of the form "18-Sep-1983, 11:42:25.056".

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_String(double UR8, char *date_string);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_String(double UR8, CharBuffer date_string);

; IDL

LONG TM_UR8_to_String(DOUBLE UR8, BYTE date_string)

Description: Get the time from the user's computer and convert it to a UR8.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_from_Local_Time(double *UR8);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_from_Local_Time(DoubleBuffer UR8);

; IDL

LONG TM_UR8_from_Local_Time(DOUBLE UR8)

Description: Convert the year, day-of-year, and milliseconds into a 64bit floating point number in UR8 format.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_from_YDOY(double *UR8, int year, int day_of_year, int millseconds);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_from_YDOY(DoubleBuffer UR8, int year, int day_of_year, int millseconds);

; IDL

LONG TM_UR8_from_YDOY(DOUBLE UR8, LONG year, LONG day_of_year, LONG millseconds)

Description: Convert a UR8 to the year, day-of-year, and fractional hours.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_YDOYH(double UR8, int *year, int *day_of_year, double *hour);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_YDOYH(double UR8, IntBuffer year, IntBuffer day_of_year, DoubleBuffer hour);

; IDL

LONG TM_UR8_to_YDOYH(DOUBLE UR8, LONG year, LONG day_of_year, DOUBLE hour)

Description: Convert a UR8 to the year, day-of-year, and milliseconds.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_YDOY(double UR8, int *year, int *day_of_year, int *millseconds
);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_YDOY(double UR8, IntBuffer year, IntBuffer day_of_year, IntBuffer millseconds);

; IDL

LONG TM_UR8_to_YDOY(DOUBLE UR8, LONG year, LONG day_of_year, LONG millseconds)

Description: Convert the year, month, day-of-month, hour, minute, second, millisecond into a 64bit floating point UR8. The month and day-of-month variables are indexed from 1.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_YDOY(double *UR8, int year, int month, int day_of_month, int hour, int minute, int second, int millisecond);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_YDOY(DoubleBuffer UR8, int year, int month, int day_of_month, int hour, int minute, int second, int millisecond);

; IDL

LONG TM_UR8_to_YDOY(DOUBLE UR8, LONG year, LONG month, LONG day_of_month, LONG hour, LONG minute, LONG second, LONG millisecond)

Description: Convert a UR8 into its component year, month, day-of-month, hour, minute, second, millisecond variables. The month and day-of-month variables are indexed from 1.

Returns: Non-zero integer on failure.

/* C */
#include "libTM.h"

int TM_UR8_to_YDOY(double UR8, int *year, int *month, int *day_of_month, int *hour, int *minute, int *second, int *millisecond);

// Java
import java.nio.*;
import edu.umn.space.swaves.TM;

int TM.TM_UR8_to_YDOY(double UR8, IntBuffer year, IntBuffer month, IntBuffer day_of_month, IntBuffer hour, IntBuffer minute,
                      IntBuffer second, IntBuffer millisecond);

; IDL

LONG TM_UR8_to_YDOY(DOUBLE UR8, LONG year, LONG month, LONG day_of_month, LONG hour, LONG minute, LONG second, LONG millisecond)

Building the C programs on Mac OS X is fairly trivial using the included makefile. Change directories to the examples/c directory in the TMlib client installation tree. As long as you have make and gcc installed and they are in your PATH, the following command will build all the examples.

unix% pwd
/Applications/STEREO/TMlib_Client/examples/c
unix% make -f makefile.example

The pwd command verifies you are in the correct directory. If the compilation is successful, you will end up with a set of binaries in your current directory.

The Java examples are a little bit easier to compile. As long as you have the tmlib.jar file in your CLASSPATH and you've verified that your TMlib installation works correctly (see section 3 of this document), then the following command will compile all of the Java examples on Mac OS X.

unix% pwd
/Applications/STEREO/TMlib_Client/examples/java
unix% javac *.java

The only difference to building the Java examples on Windows is that your current directory will be C:\Program Files\STEREO\TMlib_Client\examples\java instead of what is listed above for the Mac OS X example.

As mentioned above, IDL is the easiest to get the examples up and running in. Again, verify that your environment is setup properly and start the IDL environment with the sidl shell alias command in the directory containing the IDL examples. After starting the IDL environment, just compile the example and run it as shown below in thie Mac OS X example.

[01:23 PM] hobbes$ pwd
/Applications/STEREO/TMlib_Client/examples/idl
[01:23 PM] hobbes$ sidl
IDL Version 6.1.1, Mac OS X (darwin ppc m32). (c) 2004, Research Systems, Inc.
% Compiled module: TM_GETLIBPATH.
% Compiled module: TM_SELECT_SERVER.
% Compiled module: TM_SELECT_PORT.
% Compiled module: TM_SELECT_DOMAIN.
% Compiled module: TM_SELECT_STREAM.
% Compiled module: TM_FIND_EVENT.
% Compiled module: TM_GET_ITEM_I4.
% Compiled module: TM_GET_ITEM_R4.
% Compiled module: TM_GET_ITEM_R8.
% Compiled module: TM_GET_ITEM_CHAR.
% Compiled module: TM_ERROR_STACK.
% Compiled module: TM_HELP.
% Compiled module: TM_GET_POSITION.
% Compiled module: TM_SET_POSITION.
% Compiled module: TM_CLOSE.
% Compiled module: TM_UR8_TO_YDOY.
% Compiled module: TM_UR8_TO_YMD.
% Compiled module: TM_UR8_TO_STRING.
% Compiled module: TM_UR8_TO_STRING_FR.
% Compiled module: TM_UR8_TO_STRING_ABSOLUTE.
% Compiled module: TM_UR8_TO_STRING_COMPARISON.
% Compiled module: TM_UR8_FROM_YDOY.
% Compiled module: TM_UR8_FROM_YMD.
% Compiled module: TM_UR8_FROM_STRING_ABSOLUTE.
% Compiled module: TM_UR8_FROM_STRING_COMPARISON.
% Compiled module: TM_UR8_FROM_LOCAL_TIME.
IDL> .r apid_idl
% Compiled module: APID_IDL.
IDL> apid_idl
APID:         1285
APID:         1285
APID:         1298
APID:         1287
APID:         1298
...snip...

On the Windows platform, just open the IDLDE and the TMlib routines will automatically be compiled and available for you thanks to the IDL_STARTUP environment variable. Next, navigate to the example/idl directory of your TMlib installation and open the apid_idl.pro file. Then just click "compile" and "run" in the IDLDE and the example should start outputting the same information as the Mac OS X example above.

Coming Soon!