manual.txt

4.8kcelp语音压缩编码程序

"vnames" is an array of pointers to the names of variables saved in the data
file.  Thus, vnames[0] points to the name of the first variable, vnames[1]
points to the name of the second variable, etc.  In FORTRAN, vnames is an
array of character strings.  vnames(1) has the name of the first variable,
vnames(2) has the name of the second variable, etc.

     The format information comes from a .sg_format file when the data file is
a .sg_data file.  Other data file types have fixed formats which return a set
of parameters stored in this routine.  Listed below are the format parameters
for each of these other data file types.

Format parameters for .spd data files:
     format[0] = 1
     format[1] = 1
     format[2] = 1
     format[3] = 512
     vnames[0] = "speech_data"

(No other data file types are currently defined.)

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:

     - filename is too long
     - invalid extension in filename
     - no data file found, so can't determine format
     - the format file could not be opened
     - the format file is not complete
     - invalid value read for file type
     - invalid value read for variables/block
     - invalid value read for data type
     - invalid value read for values/block


4.1.4  File Length Routine:

     status = file_length ( chan_id, bytes, samples, blocks )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       chan_id   |   int    |   integer*4
        bytes    |  int *   |   integer*4
       samples   |  int *   |   integer*4
        blocks   |  int *   |   integer*4

     This routine returns the length of the file connected to "chan_id" in
terms of bytes, samples and blocks.  I don't know what it should do with 
real-time data files (sockets) yet.

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:

     - channel number is outside valid range
     - specified channel is not open


4.1.5  Goto Sample Routine:

     position = goto_sample ( chan_id, sample_num, how )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       chan_id   |   int    |   integer*4
      sample_num |   int    |   integer*4
         how     |   int    |   integer*4

     This routine changes the sample number that the next call to
read_variable on "chan_id" reads from.  When "how" is 0, "sample_num" is
measured from the beginning of the file (i.e. absolute positioning).  When
"how" is not 0, "sample_num" is measured from the current file position (i.e.
relative positioning).  The first sample in the file is called sample 1.  This
routine can be called only if the specified channel is a "variable channel",
that is one opened via open_var_channel.  This routine does not return an
error if the sample to be read is beyond the end of file; this condition is
reported when reading.

Returned value:

     If there are no errors, the returned value indicates the current file
position (the sample number of the next sample to be read by read_variable). A
valid sample number is 1 or greater.  If an error occurs, the returned value
is < 0. 

The following errors are detected:

     - channel number is outside valid range
     - specified channel is not open
     - this routine is for use only with variable channel types
     - the file connected to this channel prohibits positioning
     - effective sample_num is < 1


4.1.6  Read Variable Routine:

     position = read_variable ( chan_id, values, num, num_read )

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

     This routine returns the next "num" values of the variable connected to
channel number "chan_id".  "values" is an array where the returned values are
placed.  In the calling routine, this array type should match that of the
variable being returned.  The size of "n" is limited only by the array size in
the calling routine.  The actual number of values read is returned in
"num_read".  "num_read" will equal "num" unless an error (specified below)
occurs; in this case, it may be zero to num-1.  This routine can be called
only if the specified channel is a "variable channel", that is one opened via
open_var_channel.

Returned value:

     If there are no errors, the returned value indicates the current file
position (the sample number of the next sample to be read by read_variable). A
valid sample number is 1 or greater.  If an error occurs, the returned value
is < 0. 

The following errors are detected:

     - error during the file read operation
     - EOF encountered on the data file
     - channel number is outside valid range
     - specified channel is not open
     - this routine is for use only with variable channel types


4.1.7  Goto Block Routine:

     position = goto_block ( chan_id, block_num, how )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       chan_id   |   int    |   integer*4
      block_num  |   int    |   integer*4
         how     |   int    |   integer*4

     This routine changes the place from which data is read in the file
connected to "chan_id".  When "how" is 0, "block_num" is measured from the
beginning of the file (i.e. absolute positioning).  When "how" is not 0,
"block_num" is measured from the current file position (i.e. relative
positioning).  It can be used on block channels and on variable channels.  The
first block in a file is called block 1.  This routine does not return an
error if positioned beyond the end of file; this condition is reported when
reading.

     On block channels, the repositioning is as follows:

     If absolute positioning, the block number read by the next read_block is
"block_num". 
     If relative positioning, the block number read by the next read_block is
changed by "block_num" blocks. 

     On variable channels, the repositioning is as follows:

     If absolute positioning, the first sample read by the next read_variable
is sample number: 
1 + (block_num - 1) * (# of values of variable per block)
     If relative positioning, the first sample read by the next read_variable
is changed by "block_num" blocks. 

Returned value:

     If there are no errors, the returned value indicates the current file
position.  On variable channels, the returned value is the sample number of
the next sample to be read by read_variable.  On block channels, the returned
value is the block number of the next block to be read by read_block. A valid
sample number or block number is 1 or greater.  If an error occurs, the
returned value is < 0.

The following errors are detected:

     - channel number is outside valid range
     - specified channel is not open
     - the file connected to this channel prohibits positioning
     - effective block_num < 1


4.1.8  Read Block Routine:

     position = read_block ( chan_id, val_pntr )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       chan_id   |   int    |   integer*4
       val_pntr  | pointer  |   integer*4    (see below)
                 |  array   |     array

     This routine returns one block of values from the file connected to
channel "chan_id".  "val_pntr" is an array of pointers having one element for
each block variable.  The calling routine sets each pointer in the array to
specify where the values for each block variable are to go.  Thus, val_pntr[0]
is the address where the first value of the first block variable will be
stored; val_pntr[1] is the address where the first value of the second block
variable will be stored; etc.  Subsequent values of the variables are stored
in sequential locations following the address of the first value.

     For FORTRAN (ugh) users, here's what you do with val_pntr.  This array is
set up to contain for each block variable, the ADDRESS of where you want the
first value of each variable to be placed.  A routine for getting the address
of a variable is included in the disk I/O package.  To illustrate the process,
suppose you have two variables in a block and you want to store them in x and
y.  The following code fragment shows what you do: 

     INTEGER*4 GET_ADDRESS  ! get_address returns an address of type integer*4
     REAL*4 X(13)           ! there are 13 values of X per block
     INTEGER*4 Y(8)         ! there are 8 values of Y per block
     VAL_PNTR(2)            ! there are 2 variables per block

     VAL_PNTR(1) = GET_ADDRESS( X(1) )
     VAL_PNTR(2) = GET_ADDRESS( Y(1) )

     STATUS = READ_BLOCK(CHAN_ID, VAL_PNTR)

     If the X and Y arrays are stored at fixed memory addresses, the val_pntr 
array can be set just once, rather than before each use of read_block.  If the
arrays move, val_pntr must be recalculated.

Returned value:

     If there are no errors, the returned value indicates the current file
position (the block number of the next block to be read by read_block).  A
valid block number is 1 or greater.  If an error occurs, the returned value is
< 0. 

The following errors are detected:

     - channel number is outside valid range
     - specified channel is not open
     - this routine is for use only with block channel types
     - error during the file read operation
     - EOF encountered on the data file


4.1.9  Close Channel Routine:

     status = close_channel ( chan_id )

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

     This routine closes the specified channel.  Doing so makes the channel id
available for re-assignment.

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:

     - channel number is outside valid range
     - specified channel is not open


4.1.10  Disk Read Error Routines:

     print_disk_read_error ( err_num )            (Callable from FORTRAN)
     error_string = disk_read_error ( err_num )   (No FORTRAN interface yet)

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

     The disk read routines return a value which, when less than zero,
corresponds to an error number.  The disk read error routines provide a way to
turn the error number into an appropriate error message.  The disk_read_error
routine returns a brief error message corresponding to "err_num".  The
"print_disk_read_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 read routines.