manual.txt

4.8kcelp语音压缩编码程序

     - could not get a buffer for saved values


3.1.3  Save Variable Routine:

     status = save_variable ( var_id, values, num )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
        var_id   |   int    |   integer*4
        values   |  varies  |     varies
                 | (array)  |    (array)
         num     |   int    |   integer*4

     This routine saves values of a variable that has been defined.  "values"
is the array of which "num" values will be saved.  The data type of the values
array must match that declared when the variable was defined.  The routine
does NOT test for such a match.  The number of values saved per call can be
from 1 to the number per block specified when the variable was defined with
def_variable.  The total number of values saved per variable cannot exceed the
number per block specified when the variable was defined.  Note to C users:
When saving a single value, be sure that "values" is a POINTER to that value. 

Returned value:

     The returned value indicates the error status of the routine.  If no
error occurs, the returned value is 0.  If an error occurs, the value is < 0. 

The following errors are detected:

     - 'num' < 1
     - 'var_id' is out of range
     - 'var_id' corresponds to an undefined variable
     - all values of this variable have been saved in the current block
     - saved less than the specified number of values because the current
       block became full


3.1.4  End Block Routine:

     status = end_block ( file_id )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       file_id   |   int    |   integer*4

     This routine terminates the saving of variables for a block.  This is the
routine which writes the block values to the data file.  The first call to
this routine terminates the variable definition process, i.e. def_variable can
no longer be called for this file_id.  When a file is open for appending, the
first call to this routine checks to see that the variable definition of the
appended file matches the current definition.  An error is returned if not.

Returned value:

     The returned value indicates the error status of the routine.  If no
error occurs, the returned value is 0.  If an error occurs, the value is < 0. 

The following errors are detected:

     - 'file_id' is out of range
     - 'file_id' corresponds to an unopened file
     - current variable definition differs from that of appended file
     - error when writing format file
     - error when writing data buffer to disk
     - no variables have been defined


3.1.5  Close File Routine:

     status = close_file ( file_id )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       file_id   |   int    |   integer*4

     This routine closes the file associated with "file_id".  In the event
that more files need to be written than can be opened simultaneously, this
routine provides a way to close a file so that another can be opened. 

Returned value:

     The returned value indicates the error status of the routine.  If no
error occurs, the returned value is 0.  If an error occurs, the value is < 0. 

The following errors are detected:

     - 'file_id' is out of range
     - 'file_id' corresponds to an unopened file


3.1.6  Disk Write Error Routines:

     print_disk_write_error ( err_num )            (Callable from FORTRAN)
     error_string = disk_write_error ( err_num )   (No FORTRAN interface yet)

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       err_num   |   int    |   integer*4

     The disk write routines return a value which, when less than zero,
corresponds to an error number.  The disk write error routines provide a way
to turn the error number into an appropriate error message.  The
disk_write_error routine returns brief error message corresponding to
"err_num".  The "print_disk_write_error" routine prints a more elaborate error
message.  These routines return "No error" for arguments zero or greater and
"Bad value for error number" if "err_num" is not a value from one of the write
routines. 


4.0  USING THE DISK READ ROUTINES

     The disk read routines are structured to provide "channels" through which
the file variables flow.  There are two types of channels - variable channels
and block channels.  A variable channel provides access to just one of the
variables in a file, independent of how many variables the file may contain. 
A block channel provides access to all of the variables in a file.  The values
of a variable are read on a variable channel via the read_variable routine.
This routine can return any number of the variable's values in a single call.
Values are read on a block channel via the read_block routine.  This routine
returns one block of values per call.  The reading is done sequentially on
each channel type.  Two routines are provided to modify the point from which
data is read - the goto_sample routine and the goto_block routine.  There is
also a routine to read the file format and one to close channels.

The disk read routines consist of the following:
     1) read_format - reads and returns information about the data file
             format.
     2) open_var_channel - opens a channel to access one variable in a data
             file.
     3) read_variable - reads and returns values of a variable.
     4) goto_sample - re-positions the reading process so that read_variable
             will read from a different sample in the file.
     5) open_block_channel - opens a channel to access all variables in a data
             file.
     6) read_block - reads and returns the values of one block of data.
     7) goto_block - re-positions the reading process so that read_variable
             and read_block will read from a different place in the file.
     8) file_length - return the length of an open file.
     9) close_channel - close an open channel.

     To set-up a variable channel do the following.  First, call
open_var_channel to open a channel and get a channel id.  Then use
read_variable to read values and if necessary, use goto_sample or goto_block
to read non-sequentially.  Call close_channel when you no longer want to read
values of the variable on that channel.  To use a block channel, do the
following.  First, call open_block_channel to open a channel and get a channel
id.  Then use read_block to read one block's worth of values.  Use goto_block
if you need to read other than sequentially.  The read_format routine is
provided to read format information in situations when the file format is not
known at the time your program is being written. 

     If you use the auto error reporting method, a disk I/O error halts
execution and causes an error message to be printed.  If you don't use this
method, a disk I/O routine indicates an error via a negative return value.
This condition should be tested after using any of these routines and
appropriate action taken if an error occurs.  The disk read error routines
are provided to turn the return value into an error message.


4.1  Description of the Disk Read Routines

4.1.1  Open Variable Channel Routine:

     chan_id = open_var_channel ( filename, var_name )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       filename  |  char *  |  character*80  (or shorter)
       var_name  |  char *  |  character*16  (or shorter)

     This routine is called to establish a new channel to access the values of
one of the variables in a data file.  "filename" is the name of the file and
"var_name" is the name of the variable whose values are to be read.  The
variable's values are accessed with the read_variable routine.  This function
returns a channel id which is used to identify the opened channel when calling
other disk read routines.  "filename" can have an extension, but it is not
mandatory.   

If "filename" has an extension:
     a) The extension is tested for validity.  (e.g. Is it .sg_data or one of
        the other types that can be read by these routines?)  Valid extensions
        are: .sg_data  .spd
     b) If the extension is valid, open_var_channel tries to open "filename".
        If the extension is not valid, an error is returned.
If "filename" does not have an extension:
     a) Each valid extension is concatenated in turn with a copy of filename
        and the resulting filename is tested for existence.  The order is:
        .sg_data, .spd.
     b) If this file exists, open_var_channel tries to open it.
        If none of these files exist, an error is returned.

     If the file to be opened is a .sg_data file, the format information must
reside in a corresponding .sg_format file.  There is no format file associated
with .spd files.

Returned value:

     If there are no errors, the returned value is a channel id which is used
to identify the open channel when using other disk read routines.  A valid
channel id is >= 0.  If an error occurs, the returned value is < 0. 

The following errors are detected:

     - filename is too long
     - all channels are open
     - there is a format file problem
       (use read_format to determine the problem)
     - the specified variable was not found
     - invalid extension in filename
     - no data file found
     - the data file could not be opened


4.1.2  Open Block Channel Routine:

     chan_id = open_block_channel ( filename )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       filename  |  char *  |  character*80  (or shorter)

     This routine is called to establish a new channel to access the values of
all of the variables in a data file.  The values of the data file variables
are accessed with the read_block routine.  This function returns a channel id
which is used to identify the opened channel when calling other disk read
routines.  The same rules concerning filename extensions described in
open_var_channel apply to open_block_channel.

Returned value:

     If there are no errors, the returned value is a channel id which is used
to identify the open channel when using other disk read routines.  A valid
channel id is >= 0.  If an error occurs, the returned value is < 0. 

The following errors are detected:

     - filename is too long
     - all channels are open
     - there is a format file problem
       (use read_format to determine the problem)
     - invalid extension in filename
     - no data file found
     - the data file could not be opened


4.1.3  Read Format Routine:

     status = read_format ( filename, format, vnames )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       filename  |  char *  |  character*80  (or shorter)
        format   |   int    |   integer*4
                 | (array)  |    (array)
        vnames   | char **  |  character*16  (see description)
                 |          |    (array)

     This routine reads the format file associated with file "filename" and
returns this information.  As with the filename argument in the open channel
routines, read_format accepts filenames with or without extensions.  It uses
the same process that the open channel routines use to determine for what data
file the format information is sought.  Hence, for a given filename,
read_format always gets the format which corresponds to the data file opened
by an open channel routine.  (However, read_format accepts filenames that end
with .sg_format.  Such a filename would cause an error if given to an open
channel routine.)  When calling from FORTRAN, vnames should be declared:

     character*16 vnames(n)

n should be equal to or greater than the number of variables in the file.  A
safe choice for n is the maximum number of variables permitted in a file
(currently 36).

The format array contains the following information:

     format[0]   -   file type indicator
                     current meaning (could be expanded later):
                     1 if .sg_data file allows sample & block positioning;
                     0 if this is NOT allowed
     format[1]   -   number of variables/block in .sg_data file
     format[2*n]  -  data type of variable n in .sg_data file
                     1 - short; 2 - int; 3 - float
                     (integer*2; integer*4; real*4 in FORTRAN)
     format[2*n+1] - number of values/block of variable n in .sg_data file