VReadHeader

 
Name
  VReadHeader - reads the 3DVIEWNIX file header.
 
Synopsis
  VReadHeader(fp, vh, group, element)
  FILE *fp;
  ViewnixHeader *vh;                    /*RETURN*/
  char group[5];                        /*RETURN*/
  char element[5];                      /*RETURN*/
 
Description
  VReadHeader reads the 3DVIEWNIX header. VReadHeader reads the user
specified file and copies the information to structure vh according to the
data set type stored in the file header. 

Structures
  typedef struct {
        GeneralInfo gen;        /*general header information*/
        SceneInfo scn;          /*scene data header information*/
        StructureInfo str;      /*structure data header information*/
        DisplayInfo dsp;        /*display data header information*/
  } ViewnixHeader;

  See Appendix B for description of GeneralInfo, SceneInfo, StructureInfo
  and DisplayInfo.
 
Return Value
  0 - work successfully.
  1 - memory allocation error.
  2 - read error.
  5 - improper seeks.
  7 - 3DVIEWNIX directory pathname not given in environment variable.
  100 - incorrect 3DVIEWNIX file format.
  102 - invalid data set type.
  103 - cannot open specification file.
  104 - invalid value in the file header for Type 1.
  106 - invalid value in the file header for Type 1D.
  107 - invalid value in the file header for 2, 2D, or 3.
  105 - invalid recognition code.
 
Parameters
  fp - a pointer to the input file.
  vh - pointer to the ViewnixHeader structure.
  group - the group number of the error item.
  element - the element number of the error item.
 
Side Effects
  Specification of the 3DVIEWNIX data protocol is stored in three 
specification files for each version of the protocol - SCENE_V1.0.SPC, 
STRUCTURE_V1.0.SPC, and DISPLAY_V1.0.SPC which are ASCII files resident in
the 3DVIEWNIX/FILES directory. Each specification file contains the group 
number, element number, and value representation for message items marked
by a star in the data protocol document. The specification files are a 
mechanism to ensure downward compatibility with the protocol when future
enhancements are brought out and to conveniently modify the protocol when
the need arises. Every message item stored in the specification file is given
a corresponding element in the structure ViewnixHeader. An additional 1-bit 
element called a validity flag is created in ViewnixHeader for every message 
item. Of course, the file that is being read may not be compatible with the 
information stored in the specification files. The version number of the 
protocol of the data in the file is determined from the specification code 
stored as VIEWNIXm.n, where m and n stand for an integer between 0 and 9.
If the specification files and the structure corresponding to an item in 
the specification files is not found in the input file, the 
corresponding validity flag is set to 0 and no value is assigned to the 
corresponding element in ViewnixHeader. If a message item is successfully 
found, the flag is set to 1 and the value read from the file is assigned
to the element in ViewnixHeader. The structure ViewnixHeader contains both
single value pointers and fixed array fields. If an item is of type 1 or
type 1D and is not found in the file, its validity is set to 0 irrespective
of whether the item represents a single value, a pointer, or a fixed array.
In the following description, we assume that the item corresponding to a
message item in the specification files is indeed found in the input files.
VReadHeader sets the validity flag to 1 and assign the value read to the 
corresponding item, if the item is of single value type and has a length 0.
For a pointer, if the data type is char, VReadHeader sets the validity  
flag to 1 irrespective of value length. If this length is 0, VReadHeader 
assigns NULL to the pointer; if the length is not 0, VReadHeader will 
allocate memory and assign the string read from the file to the corresponding 
item. If the data type is int, short, or float and the value length is 0,
VReadHeader sets the validity flag to 0 and assigns NULL to the pointer. If 
the length is not 0 and has a value that matches what is expected, VReadHeader
sets the flag to 1, allocates memory, and assigns the value read to the 
corresponding item. If the value length is greater or less than what is 
expected, VReadHeader sets the flag to 0, allocates memory, assigns value,
but returns error 104. For fixed array type, if the data type is char,
VReadHeader sets the validity flag to 1 irrespective of value length. If the 
length is 0, VReadHeader assigns an empty string to the corresponding item.
If the length is greater than the array size defined in ViewnixHeader,
the string is truncated and assigned to the item. If the data type is 
short, int, or float and the length is 0, VReadHeader does not assign any 
value to the item but sets the flag to 0. If the length is not 0, and has a 
value that matches what is expected, the flag will be set to 1 and the 
value read will be assigned to the item. If the length is greater or less
than what is expected, VReadHeader sets the flag to 0, allocates memory,
assigns value, but returns error 104.
 
Entry Conditions
  The environment variable "VIEWNIX_ENV" must be set to the 3DVIEWNIX
system directory. The proper specification files must be present.
 
Related Functions