This document describes how to use the request event file feature of WinSDR. The purpose of this feature is to allow other programs to request event files from WinSDR. We use this feature in WinQuake for the Request Data Web page at http://www.seismicnet.com/request.html.
WinSDR checks a directory every 10 seconds for a request file. The request file has information in the file that is used by WinSDR to create the event file. This file has the start time, number of minutes to save, save nth data point (time compression), channel name, and a file name to call the saved output event file(s).
It's up to you to write a program that takes the information from the user, this could be a CGI script connected to a Web page form etc, and create the request file in the directory that WinSDR is checking every 10 seconds. If WinSDR finds a request file, it parses out the information and tries to create the event file(s). WinSDR does this by doing an automatic Replay to create and save the event file data.
After WinSDR reads the request file it deletes it. Your program needs to wait for the event file(s) to show up in the output event file directory. DO NOT have WinSDR save the event files in the same directory as the request file. The request file shared directory should only be used for the request file. WinSDR has to check this directory every 10 seconds. If there are any other files in this directory it will take longer for WinSDR to search for request files. Your program should wait for about 30 to 45 seconds for the event file or files to show up. If after this time period there is no event file found there was an error over at the WinSDR end or there is a setup problem.
WinSDR will report back an error condition by using the output file and placing a small error message in it. The user should check the file size of the event file, and, if its under 200 bytes long then there was an error, and WinSDR placed an error message (one line of ASCII text) in the file instead of the actual PSN formatted event file data.
The only thing you need to do in WinSDR is set the Request Control File field in the System Settings dialog box. Use the Browse button to select the directory that will be used to check for the request files.
The name of the request file is: RQ??????.SYn where the ?????? can be any characters to make the file name unique, and n is the system number. The system number can be changed under the System Settings dialog box, and is usually 1 if you only have one WinSDR system running. For the ?????? part of the name I use the hour, minute and seconds of the current time that the request file is created. The full file name and path used to create the request file should look something like this:
C:\SDR\REQUEST\RQ142308.SY1
If you have more than one WinSDR system, it is up to your program too know what system the channel is on. I use a simple file that my Request Web page CGI script reads to do the channel to system number mapping.
The content of the file is one single line of text with the request information in it. The fields are separated with spaces. The format of the line is:
MM DD YY HH MIN UTC/LocalChar SaveTime SaveNth# ChannelName_or_list OutputName
Where:
MM is the start time month (1 -> 12).
DD is the start time day (1 -> 31).
YY is the start time year (97 or 98 etc).
HH is the start time hour (00 -> 23).
MIN is the start time minute (00 -> 59).
UTC/LocalChar tells WinSDR if the start time is Local or UTC. This needs to be single uppercase U or L character.
SaveTime is the number of minutes to save.
SaveNth is used to control the sample rate of the event file. A 1 in this field will tell WinSDR to save every sample. A 2 in this field will save every other sample producing an event file 1/2 the size of an event file saved with a 1 for SaveNth. The sample rate of the event file will be 1/2 of the system sample rate. A 3 in this field will save every third sample (Note: WinSDR averages the data between saved samples).
ChannelName_or_list is the file name extension that is set by each Channel Setting screens. On my system the channel / file extension are called LC1 LC2 etc. More then one channel can be replayed per request file by placing more then one file name in this string. File names should be separated by a coma with out any spaces. Example: LC1,LC2 If more then one file is specified, the OutputName field directory and root name are used to create the full file name for each channel.
OutputName is the full path and file name that WinSDR will use to create the event file or it will hold an error message string if WinSDR encounters any problems. The path part of the name needs to point to a directory that WinSDR has access too. The file name part can be anything. I use the month, day, hour, minute and then the channel name for my CGI script. Example: g:\WinSDR\reqdata\02151238.LC1. This field is not used if more then one ChannelName file name is present.
When WinSDR creates an event file it appends ".psn" to the file name. The program creating the request file must look for an output file ending with ".psn".
Example of the text command in a request file:
02 15 97 12 23 U 10 1 LC1 G:\WinSDR\REQFILE\02151223.LC1
This command will request a LC1 channel event file starting at 02/15/97 12:23 (Note that seconds are not used) UTC time. The file should be 10 minutes long and have no time (Save-Nth = 1) compression. The event file will be called G:\WinSDR\REQFILE\02151223.LC1.PSN
WinSDR can be forced into an alarm state by placing the the keyword "TRIGGER" (without the "") in the first line of the request file. When WinSDR finds a request file with this keyword, the program will create one or more event files.
If you need any help getting this working please feel free to contact me.