The libVIDF is a library to enable the application developer to read from the IDFS VIDF file. The VIDF file contains a full description of the virtual instrument which includes the measurements included in the data records, the status measurements included in the header records, and the algorithms to convert each of these measurements into one or more sets of physical units. This library will support version 2.1 binary IDF files, and all ASCII versions after that. IDFS creators are encouraged to create only v3.0 VIDF files from now on since backward compatibility may be removed at a later date.
This library is dependent on the following IDFS libraries: libant, libCfg, and libserver. Other system libraries include lex and yacc (or their equivalents). When linking, make sure all the libraries are also included.
To use the libVIDF library, include "libVIDF.h" in your source code and use any of the four public calls which are documented below. One must always do an initialize before attempting to read from a VIDF. Unpredictable results will occur otherwise. Initialization can happen in one of two ways, either from a data key and an associated time, or from a filename. After an initialize, you can use the read_idf call which should be backward compatible with previous versions of the read_idf call or you may use the ReadVIDF which is more efficient. The program should then call CloseVIDF prior to completion of the program.
int ReadVIDF (SDDAS_ULONG data_key,
SDDAS_SHORT btime_yr, SDDAS_SHORT btime_day,
SDDAS_LONG btime_sec, SDDAS_LONG btime_nsec,
SDDAS_SHORT etime_yr, SDDAS_SHORT etime_day,
SDDAS_LONG etime_sec, SDDAS_LONG etime_nsec,
void *var, VIDF_DEFS what, SDDAS_SHORT which,
SDDAS_LONG start, SDDAS_SHORT len);
ReadVIDF is the call most people will use to get information from a VIDF file. The parameters are as follows:
On using new VIDF, ReadVIDF will return error code VIDF_ELEMENT_NOT_FOUND if the specified what value was not found. If it was found, it will return an ALL_OKAY. With an old VIDF, the following return codes may be returned:
SDDAS_LONG read_idf (SDDAS_ULONG data_key, char *exten,
SDDAS_USHORT vnum, void *var, SDDAS_SHORT quan, SDDAS_SHORT num,
SDDAS_LONG start, SDDAS_SHORT len);
If you are using old code, you may have other calls to read_idf which was the previous method of reading from a v2.1 VIDF. We have deprecated the use of this call since we added the time into the call. This enables us to have the VIDF be more time dependent so multiple VIDF files will be handled better and in control of the user. The seperation also allows us to handle either a new or old style VIDF to maintain backwards compatibility. Furthermore, the first three variables are no longer used.
Nevertheless, the call is still available so MOST of your code will not change at all. Please read the appendix dealing with incompatibilities between the old and the new calls.
The only time this call will not work is if you call this function without first opening the VIDF which the IDFS read routines will do for you. If you do not use the IDFS read routines, you MUST use the new ReadVIDF routine.
void CloseVIDF ();
This call takes no arguments and returns nothing. It will simply close the file descriptor associated with the VIDF file. If you use the IDFS read routines' free_experiment_info, you should not have to make this call.
int InitializeVIDFFromFile (char *);If you know the name of the file prior to opening, call InitializeVIDFFromFile with the filename of the VIDF file. The file must end in either a "I" or a "V.v3". Based on the extension, the initialize routine will use either the old or the new read routines to read the VIDF file.
If the IDFS read routines are being utilized, it will already have made this call and you may just you the routines below to access the current VIDF in memory.
InitializeVIDFFromFile will return an error code if the VIDF can not be opened. Otherwise, ALL_OKAY will be returned.
int ReadFromCurrentVIDF (void *var, VIDF_DEFS what, SDDAS_SHORT num,
SDDAS_LONG start, SDDAS_SHORT len);
If you used InitializeVIDFFromFile, you will not have a data key or a time. There
will only be one VIDF available so you may use the call ReadFromCurrentVIDF
to read information from a VIDF. The parameters (which are identical to
the related counterparts in ReadVIDF) are as follows:
For most people, there is no change needed in using this new library; however, there are several backward incompatibilities between the old read_idf call and the new read_idf call.
The most prominent one is in calling read_idf expecting an array of strings. read_idf no longer expects a preallocated space for the string. It will now return a string pointer which is more memory efficient.
Any field designated as a comment in v2.1 of the VIDF are no longer retrievable using the new VIDF. The reason is comments are now allowed anywhere in the VIDF and you are no longer restricted to their line length or frequency. As a result, they are not retrievable.