elements written to the file pointed to by the 'sp_file' structure.Incomplete writes are not flagged by the function.  It is theprogrammer's responsibility to make sure that the return value equals'n'.See Also:    sp_eof(), sp_error(), sp_set_data_mode()II.C.3 sp_set_data_mode()Description:       Changes the default behavior of the SPHERE File I/O functions, 'sp_read_data()' and 'sp_write_data()'.Syntax:    int sp_set_data_mode(SP_FILE *sp_file, char *mode)Arguments:    Specifies the waveform transformations for data read from, orwritten to, the file pointed to by 'sp_file'.  The transformations arespecified in the string, 'mode'.  See the "Remarks" section for theformat and permissible values of this string.Remarks:    The 'mode' string argument specifies sample encoding and byteorder transformations to be performed by the SPHERE File I/Ofunctions, 'sp_read_data()' and 'sp_write_data()'.  (Future versionsmay support sample rate transformations as well.)  The 'mode' stringhas the following format:        MODE        :==  <MODE_FLAG>:<MODE>        MODE_FLAG   :==  SE-<SE_OPTIONS> | SBF-<SBF_OPTIONS>        SE_OPTIONS  :==  PCM | PCM-1 | PCM-2 | ULAW | RAW | ORIG |                         SHORTEN | WAVPACK	SBF_OPTIONS :==  01 | 10 | 1 | N | ORIGMode Flag and Option Descriptions:    SE -> specifies a transformation to the encoding of the sampled	  waveform data.        SE_OPTIONS:            "PCM-2"   -> Read or write data as 2-byte PCM samples.            "PCM-1"   -> Read or write data as 1-byte PCM samples.            "PCM"     -> Synonym for "PCM-2"            "ULAW"    -> Read or write data as 1-byte ULAW samples.  	    "RAW"     -> Read or write data as 1-byte character	                 stream (for unsupported data types).            "ORIG"    -> Read or write data as-is.	    "SHORTEN" -> Write data as Shorten-compressed byte stream.	    "WAVPACK" -> Write data as Wavpack-compressed byte stream.        SBF -> specifies a transformation to the byte format (byte order)	   of the sampled waveform data.  This is only appropriate for           multi-byte sampled data.        SBF_OPTIONS:            "01"      -> Read or write data as LSB/MSB.            "10"      -> Read or write data as MSB/LSB.            "1"       -> Read or write data as 1-byte samples.            "N"       -> Read or write data as natural to the host.            "ORIG"    -> Read or write data as-is.Currently Supported Sample Encoding (SE) Read Transformations: ***    PCM-2   -->  ULAW | RAW | ORIG    PCM-1   -->  PCM-2 | ULAW | RAW | ORIG    ULAW    -->  PCM-2 | PCM-1 | RAW | ORIG    RAW     -->  ORIG    SHORTEN -->  PCM-2 | PCM-1 | ULAW | RAW | ORIG    WAVPACK -->  PCM-2 | PCM-1 | ULAW | RAW | ORIG    Currently Supported Sample Encoding (SE) Write Transformations: ***    PCM-2   -->  PCM-1 | ULAW | ORIG | SHORTEN | WAVPACK     PCM-1   -->  PCM-2 | ULAW | ORIG | SHORTEN | WAVPACK     ULAW    -->  PCM-2 | PCM-1 | ORIG | SHORTEN | WAVPACK     RAW     -->  ORIG*** NOTE: The current version of SPHERE does not support conversions          to and from the ulaw sample format. Return Value:    The value returned by 'sp_set_data_mode()' is 0 if thetransformation specified by 'mode' is supported, a 100 ifthe transformation is not supported, and greater than100 on error.See Also:    sp_read_data(), sp_write_data(), sp_open(), sp_close()II.D   Status FunctionsII.D.1 sp_eof()Description:    Returns the End-of-File (EOF) status of an opened SPHERE file.Syntax:    int sp_eof(SP_FILE *sp_file)	Arguments:    sp_eof takes as it's argument a SPHERE file pointer, 'sp_file',and returns the EOF status of that file.Return Value:    sp_eof returns a non-zero value if the end-of-file has beenreached during the last file read.  Otherwise, it returns a zero.See Also:    sp_read_data(), sp_error()II.D.2 sp_error()Description:    Returns the error status of an opened SPHERE file.Syntax:    int sp_error(SP_FILE *sp_file)	Arguments:    sp_error takes as it's argument a SPHERE file pointer, 'sp_file',and returns the error status of that file.Return Value:    sp_error returns a zero if no errors occurred during the last fileI/O operation, a 100 if a checksum verification error occurred, or greaterthan 100 if a fatal file I/O error occurred.See Also:    sp_read_data(), sp_write_data(), sp_eof()II.D.3 sp_print_return_status()Description:    Prints the return status of the last SPHERE function call.Syntax:    int sp_print_return_status(FILE *fp)Arguments:        sp_return_status takes as it's argument an opened file pointer,'fp', and prints a message indicating the sucess or failure of thelast SPHERE function called to 'fp'.Remarks:    sp_return_status prints the following report for the lastfunction called:    Function: <function-name>    Status code: <integer-value>    Status type: <Success|Warning|Error>    Message: <message-string>Failures of child functions are recorded in the Message string.Note: This is currently only defined for the SPHERE 2.0 C-languageProgrammer Interface Library functions.Return Value:        sp_return_status a zero on sucess and a 100 or greater on error.II.D.4 sp_return_status()Description:    Returns the return status of the last SPHERE function call.Syntax:    int sp_return_status()Return Value:        sp_return_status returns the status of the last SPHERE functioncall.  The SPHERE 2.0 C-Language Programmers Interface Library functionsfollow the conventions below for indicating Success, Warnings, orErrors:     	Return Condition	Possible Range of Values	---------------- 	------------------------	   Success		           0	   Warning                        1-99	   Fatal Error	             100 or greaterNote: This is currently only defined for the SPHERE 2.0 C-languageProgrammer Interface Library functions.III.  File Format DefinitionSPHERE files contain a strictly defined header portion followed bythe file body (waveform).  Any waveform encoding may be used, but theencoding must be sufficiently described in the header.The header is an object-oriented, 1024-byte blocked, ASCII structurewhich is prepended to the waveform data.  The header is composed of afixed-format portion followed by an object-oriented variable portion.The fixed portion is as follows:NIST_1A<new-line>   1024<new-line>The first line specifies the header type and the second line specifies theheader length.  Each of these lines are 8 bytes long (including new-line) andare structured to identify the header as well as allow those who do not wishto read the subsequent header information to programmatically skip over it. The remaining object-oriented variable portion is composed ofobject-type-value "triple" lines which have the following format:<LINE> --> <TRIPLE><new-line> |           <COMMENT><new-line> |            <TRIPLE><COMMENT><new-line> |   <TRIPLE> --> <OBJECT><space><TYPE><space><VALUE><OPT-SPACES>    <OBJECT> --> <PRIMARY-SUBOBJECT> |                  <PRIMARY-SUBOBJECT><SECONDARY-SUBOBJECT>    <PRIMARY-SUBOBJECT> --> <ALPHA> | <ALPHA><ALPHA-NUM-STRING>    <SECONDARY-SUBOBJECT> --> _<ALPHA-NUM-STRING> |                               _<ALPHA-NUM-STRING><SECONDARY-SUBOBJECT>    <TYPE> --> -<INTEGER-FLAG> | -<REAL-FLAG> | -<STRING-FLAG>      <INTEGER-FLAG> --> i      <REAL-FLAG> --> r      <STRING-FLAG> --> s<DIGIT-STRING>          <VALUE> --> <INTEGER> | <REAL> | <STRING>  (depending on object type)      <INTEGER> --> <SIGN><DIGIT-STRING>      <REAL> --> <SIGN><DIGIT-STRING>.<DIGIT-STRING>     <OPT-SPACES> --> <SPACES> | NULL  <COMMENT> --> ;<STRING>  (excluding embedded new-lines)<ALPHA-NUM-STRING> --> <ALPHA-NUM> | <ALPHA-NUM><ALPHA-NUM-STRING><ALPHA-NUM> --> <DIGIT> | <ALPHA><ALPHA> --> a | ... | z | A | ... | Z<DIGIT-STRING> --> <DIGIT> | <DIGIT><DIGIT-STRING><DIGIT> --> 0 | ... | 9<SIGN> --> + | - | NULL<SPACES> --> <space> | <SPACES><space><STRING> -->  <CHARACTER> | <CHARACTER><STRING><CHARACTER> --> char(0) | char(1) | ... | char(255)The following fields are required for proper SPHERE I/O handling.These fields completly describe the geometry of the data contained inthe SPHERE file.        Field_name         Field_type	----------         ----------	sample_count           -i	sample_n_bytes         -i	channel_count          -iThe following fields are optional:        Field_name         Field_type	----------         ----------	sample_checksum        -i               sample_coding          -s       (If missing, defaults to 'pcm')        sample_byte_format     -s       (If missing, defaults to the Host's                                         natural byte format.)The following fields are conditionally required:        Field_name         Field_type   Required if:	----------         ----------   ------------	sample_rate            -i       (the 'sample_coding' field is					 missing, or contains 'pcm' or 'ulaw')Possible values for these fields are:	sample_count -> 1 .. MAXINT	sample_n_bytes -> 1 | 2	channel_count -> 1 .. 32	sample_byte_format -> 01 | 10 | 1 (* See below for exception)	sample_checksum -> 0 .. 32767	sample_rate -> 1 .. MAXINT	sample_coding -> pcm | ulaw | pcm,embedded-shorten-vX.X | 			 ulaw,embedded-shorten-vX.X |			 pcm,embedded-wavpack-X.X | 			 ulaw,embedded-wavpack-X.X |			 pcm,embedded-shortpack-X.X (Read Only)	* Note: The original recordable CD-ROM release of WSJ0 incorporated	        "shortpack" waveform compression.  The compression was 		indicated by the now outmoded presence of the string,		'shortpack-v0',	in the 'sample_byte_format' field.		Since this software attempts to support all previous		NIST releases of speech corpora, this "non-standard"		field value is permitted.  Please note that this		software will not generate files with this field value		and that the LDC is producing a CD-ROM release of WSJ0		which conforms to the specifications defined in SPHERE 2.0.The single object "end_head" marks the end of the active header and theremaining unused header space is undefined. A sample header is includedbelow.Example SPHERE header from the TIMIT corpus (NIST Speech Disc 1-1.1):NIST_1A   1024database_id -s5 TIMITdatabase_version -s3 1.0utterance_id -s8 aks0_sa1channel_count -i 1sample_count -i 63488sample_rate -i 16000sample_min -i -6967sample_max -i 7710sample_n_bytes -i 2sample_byte_format -s2 01sample_sig_bits -i 16end_headExample SPHERE header from the CSR Phase II corpus:NIST_1A   1024microphone -s21     Sennheiser HMD414recording_site -s4  SRIdatabase_id -s8     wsj1database_version -s3 1.0recording_environment -s38 quiet office, door closed (room EJ186)speaker_session_number -s2 01session_utterance_number -s2 01prompt_id -s8 adapt.01utterance_id -s8 460a0101speaking_mode -s15 read-adaptationspeaker_id -s3 460sample_count -i 82561sample_min -i -560sample_max -i 655sample_checksum -i 27320recording_date -s11 11-Nov-1992recording_time -s11 12:14:16.00channel_count -i 1sample_rate -i 16000sample_n_bytes -i 2sample_byte_format -s2 01sample_sig_bits -i 16sample_coding -s25 pcm,embedded-shorten-v1.1end_headIV.  File Pointer StructureThe following is a description of the file pointer structure used bySPHERE to address opened files.The structure includes pointers to the parsed header, the waveform,and a structure used by SPHERE to track the status of variousoperations on the opened file.NOTE:   The SPHERE file pointer structure has been designed to be used	exclusively by the SPHERE library functions.  The programmer	should only include the structure in argument lists passed to	SPHERE function calls.  The programmer should NOT attempt to	manipulate this structure directly.    SPHERE Structure 'SP_FILE' 	typedef struct sphere_t SP_FILE;	struct sphere_t {       		struct header_t *header;                struct waveform_t *waveform;		struct spfile_status_t *status;	};        struct waveform_t {	        /* This structure is intended for use only by */		/* the SPHERE-library functions               */        };        struct spfile_status_t {	        /* This structure is intended for use only by */		/* the SPHERE-library functions               */	};	struct header_t {	        /* This structure is intended for use only by */		/* the SPHERE-library functions               */	};V.  InstallationTo install SPHERE on a Unix system, cd into the 'nist' directory ofthe SPHERE distribution hierarchy and type the command:	sh src/scripts/installThe SPHERE libraries will be created and placed in the 'lib'directory, and the sample programs, described in the 'System-LevelUtilities' section, will be compiled and placed in the 'bin'directory.  Installation on non-Unix systems without "make" and "sh"will probably require manual compilation.  The next release of SPHEREwill support compilation of SPHERE on PC's.Included with this release is a functional interface test programwhich exercises various header manipulation and waveformcompression/decompression functions.  To run the test, execute thecommand from the 'nist' directory in the distribution hierarchy:	tsphere -d lib/dataThe program requires the files in the 'lib/data' directory of theSPHERE distribution hierarchy.  If all is well, the program will runwithout errors.  If an error occurs, send a bug report as specified inthe 'Bug Reports' section.VI.  Linking to the SPHERE libraryUser programs are linked with two object code libraries: