Readme file for oform.exe x12

Roger De Roo  2012 Oct 19

oform is a compiled program that communicates via
the Prologix USB-GPIB interface with an hp or Agilent Network Analyzer (NWA).
oform is a modified version of the example C-code 
SerialTest from the Prologix website  (www.prologix.biz).
oform is short for "outpform", the GPIB command to the NWA to get the data.
oform has been compiled on a Win7 platform and run on a WinXP platform
with an hp8753D (at least, an earlier version of oform) and an Agilent 8722ES.  
It should work with an hp8510 also.

The first time any prologix application is run, the USB driver
will need to be downloaded from the prologix website.

Copy the executable oform.exe program found in the Release subfolder to
where you wish to save NWA data.
Both programs are best run from a command line interface.
Click "Start -> Run...", enter "cmd", and hit "OK" to get a command line interface.
The command line interface is the remnant of Microsoft's DOS, 
which was a poor imitation of Unix. 
useful commands include: 
cd - change directory
mkdir - make a directory
del - delete a file
more - print a text file to the standard output
the command line interface also supports redirection to a file (">") and command pipes ("|"), 
just as they are used in Unix.

------------oform.exe    (version 12)

oform is a program that acquires the active data from the NWA and puts it
on the standard output.
As standard output, the data can be directed to a file with the ">" operator:
oform > filename
Thus, custom file names are much easier to make using oform than can be done on the NWA
when saving to floppy, where you need to enter characters using the NWA thumbwheel.
Errors (eg. the USB is unplugged, the Prologix device is not attached to the NWA)
are reported to standard error, so they always appear on the screen even if the
oform output is redirected to a file.

oform executes an OUTPFORM command to get the data.  This is the last accessable
NWA data register prior to display, to provide the greatest flexibility in use.
To get data equivalent to that in earlier registers in the data flow, 
turn off the appropriate data operations (eg. cal, averaging, etc.).
See the NWA programming manual for data flow operation details.

New in version x12:
oform is more graceful about commands the NWA doesn't recognize.
Fields in the header, or in the body of data, may be populated with "(err)"
or zero.

New in version x11:
bug that treats Prologix GPIB-USB firmware 6.1xx as older than 6.91 fixed.

New in version x10:  
oform supports the usage guide switch -h or --help
oform supports the version switch -v or --version
If either of these switches is used, oform outputs the usage or version number 
to standard error, and stops execution.
oform does not yet support any other switches.
oform does take an abritrary number of commands on the command line and
attempts to control the Prologix or the NWA with them.  The commands are
sent after the Prologix converter is configured and after the NWA has been
identified, but before any of the settings of the NWA are queried.
This feature can enable oform to be used in a script to autocycle 
thru all of the S-parameters. For example:
oform s11 > somefile
will tell the NWA to measure the reflection on port 1 before querying for the
settings and offloading them and the measurement data into the file somefile.
Of course, oform still operates without additional commands, preserving the
current NWA settings.

Features of the output file:
The header of the file should be compatable with the .csv file
format when saving NWA data to the NWA floppy disk.
As implied by csv, the fields are seperated by commas.
These fields include
line 1,2:
a NWA identification string, the NWA firmware version, and the NWA firmware date (I don't know how to get this)
line 3,4:
The date and time as known by the NWA
line 5,6:
the active channel, the active measurement (eg. S21) including memory operations, if applicable
(eg. S21/M), and the format (eg. LOGM).
line 7,8:
the start and stop frequency (format change:  in MHz, not Hz), or (if in time-domain),
the start and stop time (format change:  in ns, not in s)
line 9,10:
the number of points, the power setting (in dBm), and IF bandwidth (in Hz)
line 11 is a header for the data fields that follow
line 12 to 11+(the number of points) consist of 
the frequency (in MHz) or time (in ns)  [this is incompatible with the Hz or s in the floppy files],
the magnitude (in dB), and
the phase (in deg).

Extensions to the standard csv format occur later in the header lines, after the compatable fields.
lines 1,2:
software version number of oform and
the Prologix firmware version number (must be 6.91 or greater, or the code will complain.  
Go to the prologix website to download an update).
lines 5,6:
a field indicating if the time-domain transform is on (1) or off (0).
lines 9,10:
the smoothing factor, the averaging factor (0 if off), and whether a cal is on (1) or not (0), and a field for the sweep time (in seconds).

The output data itself is an improved version of what one gets from saving data to floppy.
The NWA is put into polar mode just prior to downloading data (and the NWA is then returned
to the previous format before oform completes).  In polar format, real and imaginary parts of 
the data are downloaded, from which magnitude and phase are extracted.  For all formats
other than polar or smith chart, the NWA data save to floppy contains ONLY that data shown
in the format:  ie. the magnitude, or the phase, etc. but never enough to reconstruct 
both the magnitude and phase.

Any GPIB errors (esp. the annoying "addressed to talk with nothing to say") on the NWA 
screen are erased prior to oform program termination.  Also, the NWA is put into local 
(so you can use the NWA front panel right away) just prior to oform program termination.

oform knows how many points to download, so it will work with any number of points setting.
oform downloads in FORM1 (hp/agilent's internal data representation, which is the most compact
data format at 6 bytes per point) for speed.

Limitations of oform:  Isn't graceful about GPIB errors;
isn't sophisticated in error handling in general.  
The first execution sometimes produces no data.
Likely other problems that are yet undiscovered:  
I'm a microwave engineer by training, not a software programmer.
oform is provided "as is", and is in the public domain.