gsac-client is a command-line utility designed to do two things:
1) query a GSAC Retailer Service for information about data
2) act as a FTP/HTTP client which can download files

Without further ado, let's dive into the tutorial.

Running gsac-client

If you have not already downloaded the utility, head over to the download section of the web site and grab a fresh copy of the gsac-client for your preferred platform. If you are running a Unix-based operating system such as Solaris or Linux, you can either drop the file into a directory which is in your PATH environment variable, or execute it by typing ./gsac-client. Under Microsoft Windows, open a command prompt window, change into the directory containing the file and type the command 'gsac-client'.

gsac-client Functions

The first thing you will notice is that running the utility without any options results in a list of helpful information being displayed. An 'option' is how you interact with the utility. They are basically letters or words preceeded by a single ('-') or double dash ('--'). Some options require parameters.

gsac-client utility requires that you tell it what to do, referred to as a 'function', using the '-f' option. Just remember -f = function. The function option almost always requires additional options to make it complete. There are currently four functions including status, info, count, and data.

Status Function

Let's give the status function a try 'gsac-client -f status'.

$ gsac-client -f status
Sending initial query to GSAC (gsac.ucsd.edu)....
# Server Name : SOPAC
# Server Contact : sopac@ucsd.edu
# Server Version : 1.43
# Server Status : online
# Server Options : LIMIT BOUNDING_BOX
# Client Host : josh.ucsd.edu
# Client Name : gsac-client
# Client Version : 1.15

Taking a look at the results of the status function, you can glean some useful information. The server name is provided along with an email address in case you need to contact the Retailer. You also see (hopefully) that the site is 'online' which means it is open for business. Any optional server options are also dsiplayed. You can also find out what version of gsac-client you are running.

Count Function

The status function is useful to get information about the Retailer, but it does not do anything truely productive. Of the four functions that are available to you, two are used to query the GSAC Retailer Service for information about data, including count and info. The count function is used to find out how many records match a certain query.

The count function does not do anything without additional options.

In order for the count function to do its job, let's add a few options. In order to find out how many 'rinex_obs' files are available on the 80th day of year 2002, you would type the following command:

$ gsac-client -f count -t rinex_obs -d 080 -y 2002
Sending initial query to GSAC (gsac.ucsd.edu)....
724 records match your request

You now know that 724 rinex_obs files are available.

Dates

Three-digit days are the norm in the GPS community. Rather than worrying about months, you simply need to deal with day-of-the-year and year. The date option '-d' requires a three-digit number. For example, if you want to look at the first day-of-the-year, you would use '-d 001'. When you specify a day, you also need to specify a four-digit year.

Data Types

There are currently seven different data types avaiable, but that number is likely to increase over time. A description of the different data types is beyond the scope of this tutorial.

Data Types

• rinex_obs
• rinex_met
• rinex_nav
• raw
• igs_site_log
• orbit_sp3
• sinex

You can ask for multiple data types by using the '-t' option multiple times. For example, to find out how many rinex_obs, rinex_met, and rinex_nav are available for the first day of 2000, you would use the following command:

$ gsac-client -f count -t rinex_obs -t rinex_met -t rinex_nav -d 001 -y 2000
Sending initial query to GSAC (gsac.ucsd.edu)....
203 records match your request

Span of Time

Sure, it is great to know how many files exist for a certain day, but what about a certain week? gsac-client can deal with time spans. The start day '-sd' and start year '-sy' options begin the time span and the end day '-ed' and end year '-ey' options end the time span.

If you want to find out how many rinex_obs records are available between day 85 and 90 of year 2002, here is the command you would use.

$ gsac-client -f count -t rinex_obs -sd 085 -sy 2002 -ed 090 -ey 2002
Sending initial query to GSAC (gsac.ucsd.edu)....
3918 records match your request

There is no default for year, it must be specified.

Limiting by Site

What about getting information about a single site? The '-s' option is used to limit your query to a certain site. You must use the Unique Site Id.

For example, here is a query to find out how many rinex_nav files exist on the 80th day of 2002 for SOPAC site ID sio30000:

$ gsac-client -f count -t rinex_nav -d 080 -y 2002 -s sio30000
Sending initial query to GSAC (gsac.ucsd.edu)....
1 record matches your request

The query tells you that there is one record exists. (NOTE: use the Get Single Site Information utility to get the SOPAC site ID for a four-character site code.)

Info Function

Getting a count of available records it wonderful, but what if you want to find out where the files actually live? The info function returns a list of the URL's for the data you are interested in. The URL can be an FTP or an HTTP link to the file.

Let's replace the last count example with an info function.

$ gsac-client -f info -t rinex_nav -d 080 -y 2002 -s sio30000
Sending initial query to GSAC (gsac.ucsd.edu)....
ftp://lox.ucsd.edu/pub/nav/2002/080/sio30800.02n.Z,68457,rinex_nav,2374545,sopac
1 record matches your request

The query returns a URL to the file.

The Quiet Option

The informational output displayed on the screen is actually provided in standard error. This means that you can redirect the output to a file, and only the URL will actually appear in the file.

$ gsac-client -f info -t rinex_nav -d 080 -y 2002 -s sio30000 > sio3-results
Sending initial query to GSAC (gsac.ucsd.edu)...mo.
1 record matches your request
$ cat sio3-results
ftp://lox.ucsd.edu/pub/nav/2002/080/sio30800.02n.Z,68457,rinex_nav,2374545,sopac

In this case, notice that the screen output did not include the URL since it was directed to standard output.

The quiet option will remove the informational messages sent to standard error.

For example, the following command displays only the URL:

$ gsac-client -q -f info -t rinex_nav -d 080 -y 2002 -s sio30000
ftp://lox.ucsd.edu/pub/nav/2002/080/sio30800.02n.Z,68457,rinex_nav,2374545,sopac

You can also redirect the output to a file using the quiet '-q option which results in no screen output.

$ gsac-client -q -f info -t rinex_nav -d 080 -y 2002 -s sio30000 > sio3-results

This is a great option for crontab commands.

Downloading Data

One great feature of gsac-client is the ability to have it fetch data for you. At this point, you should be pretty familiar with searching for information using the count and info functions. The data function is used to download data.

When downloading a file from an FTP site, the gsac-client logs in as anonymous. Many FTP sites require a valid e-mail address be used as the password for anonymous logins. It is helpful, and not to mention polite, to use this option when requested. The FTP server administrator might notice that a few thousand files per day are being downloaded by a particular customer. Perhaps a gsac-client command was placed into a crontab job, but was accidently mistyped, resulting in a huge load on the remote FTP server. By providing a valid e-mail address, the FTP administrator has the ability to contact you.

The email '-e' option is used to provide an e-mail address as an FTP password when necessary. Adding the '-e' option is pretty easy in a cron job, but painful to type every time you use the utility interactively. The preferred solution is to place an e-mail address in the GSAC_USER_EMAIL_ADDRESS environment variable. Once you do this, you will not have to worry about the '-e' option again. Here is an example of the '-e' option in action:

$ gsac-client -f data -t rinex_nav -d 080 -y 2002 -s sio30000 -od dl -e bgilmore@host.ucsd.edu
Sending initial query to GSAC (gsac.ucsd.edu)....
Fetching (1 of 1) files (68457 bytes) into (dl)....

Example using the GSAC_USER_EMAIL_ADDRESS variable:

$ echo $GSAC_USER_EMAIL_ADDRESS
bgilmore@host.ucsd.edu
$ gsac-client -f data -t rinex_nav -d 080 -y 2002 -s sio30000
Sending initial query to GSAC (gsac.ucsd.edu)....
Fetching (1 of 1) files (68457 bytes) into (.)...

Output Directory

By default, downloaded files get placed into your current working directory as noted by the '(.)' in the previous example. A dot '.' in Unix represents your current directory. To place the files into a different directory, use the output directory '-od' option. For example, to download data into the directory '/tmp', here is the command:

$ gsac-client -f data -t rinex_nav -d 080 -y 2002 -s sio30000 -od /tmp
Sending initial query to GSAC (gsac.ucsd.edu)....
Fetching (1 of 1) files (68457 bytes) into (/tmp)...

Rather than using a fully qualified path, you can download data into a directly beneath your current directory by removing the preceeding slash:

$ gsac-client -f data -t rinex_nav -d 080 -y 2002 -s sio30000 -od tmp
Sending initial query to GSAC (gsac.ucsd.edu)....
Fetching (1 of 1) files (68457 bytes) into (tmp)...

Bounding Box

One very popular feature of gsac-client is the Bounding Box option. This option may not be available at all GSAC Retailers because it requires special Spatial options be supported by the database. The bounding box allows you to limit your query to a particular area by using the '-bb' option. The option requires four comma separated parameters including longitude, latitude, decimal, and degree. Here is an example of bounding box in action:

$ gsac-client -f count -t rinex_met -sd 001 -sy 1998 -ed 200 -ey 1998 -bb -100,30,-90,40
Sending initial query to GSAC (gsac.ucsd.edu)....
1600 records match your request

The Bouding Box option can take a little while to perform, depending on the performance of the Retailer's server equipment, but it sure is helpful.

This concludes the tutorial for the GSAC Command Line Client. For more information, please see the gsac-client Usage document in the Documentation section of the web-site.