manual.txt

4.8kcelp语音压缩编码程序

            USER'S GUIDE TO THE SUNGRAPH FORMAT DISK I/O ROUTINES

                                  JULY 1988



                              TABLE OF CONTENTS

1.0  INTRODUCTION

2.0  GENERAL INFORMATION
     2.1 Supported Data Types
     2.2 The Concept of Data Blocks
     2.3 Files Associated with Disk I/O
     2.4 Calling the Disk I/O Routines from C
     2.5 Calling the Disk I/O Routines from FORTRAN
     2.6 Error Reporting

3.0  USING THE DISK WRITE ROUTINES
     3.1 Description of the Disk Write Routines
          3.1.1 Open File Routine
          3.1.2 Define Variable Routine
          3.1.3 Save Variable Routine
          3.1.4 End Block Routine
          3.1.5 Close File Routine
          3.1.6 Disk Write Error Routines

4.0  USING THE DISK READ ROUTINES
     4.1 Description of the Disk Read Routines
          4.1.1 Open Variable Channel Routine
          4.1.2 Open Block Channel Routine
          4.1.3 Read Format Routine
          4.1.4 File Length Routine
          4.1.5 Goto Sample Routine
          4.1.6 Read Variable Routine
          4.1.7 Goto Block Routine
          4.1.8 Read Block Routine
          4.1.9 Close Channel Routine
          4.1.10 Disk Read Error Routines


1.0  INTRODUCTION

     A set of routines to transfer data between programs and disk was
developed as part of the SUNGRAPH project.  The primary use of these routines
is to transfer data from a program to SUNGRAPH.  In this case, the user's
program uses only the disk write routines.  Another use for these routines is
to pass data between user's programs in situations where disk storage is
needed, but display with SUNGRAPH is not necessary.  In this case, the user
will need to use the disk read routines as well.  This document describes
each disk I/O routine and how to use them.  It does not describe the actual
format of the disk files which the routines use.


2.0  GENERAL INFORMATION

     The disk I/O routines are written in C and are available on the Alliant
and the Suns.  Calling them from C programs is just like calling any C
function.  Porting the routines to other machines should be straightforward.
A FORTRAN interface to the I/O routines is provided for the Alliant and Sun
machines.  These interfaces are machine dependent and therefore don't port
easily to other machines.

2.1  Supported Data Types

     The disk I/O routines enable users to write and read variables of several
data types.  The current version supports two and four byte integers and four
byte floating point variables.  Other data types can be added quite easily as
the need arises. 

2.2  The Concept of Data Blocks

     A data file can contain the values of one or more variables.  The files
and the routines which read and write them are organized around the concept of
data blocks.  A data block is the elementary unit of a data file and consists
of one or more values of each variable stored in the file.  When a new file is
created, the user decides how many variables the file will have and how many
values of each variable will be saved per data block.  A data file consists of
an arbitrary number of concatenated data blocks.

2.3  Files Associated With Disk I/O

     Data files created by the disk write routines have the extension
.sg_data.  These files consist entirely of data saved by the user; there is NO
header or record information.  Associated with each data file is a format file
having the extension .sg_format.  The format file (which has the function of a
small header) has information about the data file.  The format file contains
the following: 

     a) a number indicating data file type
     b) the number of variables in the data file
     c) for each variable in the file:
          1) data type
          2) number of values per block
          3) name

The description for the read_format routine contains additional information
about the format file.

     Any file written with the disk write routines can be read with the disk
read routines.  One other type of file can be read.  This data file must have
the extension .spd (SPeech Data).  These files usually originate by A/D
conversion of a signal of interest, such as speech.  To be an spd file, the
following must hold: 

     a) the data consists entirely of 16 bit integers stored in the binary
format of the Alliant or Sun (or machine with equivalent representation).  In
FORTRAN, this is an integer*2.  In C, it is a short int.
     b) the sample values are from a single data source.  i.e. the file has
values of a single variable; it is not multiplexed. 

2.4  Calling the Disk I/O Routines from C

     All object code that you need to link to is contained in one archive
file.  "disk_io.h" is a header file which contains definitions of some
parameters in the read and write routines.  You may want to use some of these
definitions in your program, but this is not necessary.  The files are located
as follows: 

          diskio/disk_io.h
          diskio/disk_io.a


2.5  Calling the Disk I/O Routines from FORTRAN

     Most of the disk I/O routines can be called from FORTRAN; exceptions
are noted in the routine descriptions.  When calling these routines from
Alliant FORTRAN, string arguments passed to the I/O routines are required to
be terminated with a null.  Put the null right after the last valid character. 

     All object code that you need to link to is contained in one archive
file.  The location of the object files is as follows: 

          diskio/disk_io.a

     The "released" directory also contains source code for all object files
in the archive file. 

2.6  Error Reporting

     The disk I/O routines check for all but the most unlikely error
conditions.  There are two error reporting methods which the user can select
from.  The default method is that when an error is detected, an error message
is printed.  Program execution is then halted.  The default method is called
auto error reporting.  The other error reporting method is for the disk I/O
routine to return a negative number.  (Disk I/O routines return zero or a
positive number when successful.)  The user checks the return value and takes
appropriate action.  All return values are type int (integer*4 in FORTRAN).  A
routine to turn an error number into an error message is provided.  The
following routine allows the user to change the error handling method. 

     disk_io_erh(flag)   flag is an int (integer*4 in FORTRAN)

When 'flag' is zero, auto error reporting is disabled
When 'flag' is not zero, auto error reporting is enabled.

     The error handling method can be changed as often as you want, thus
allowing some error conditions to be handled automatically and others to be
handled by the user.


3.0  USING THE DISK WRITE ROUTINES

     There are five routines in the disk write collection:
     1) open_file - opens a file for writing;
     2) def_variable - defines attributes of a variable to be saved;
     3) save_variable - saves the values of a variable;
     4) end_block - declares that all values of the variables have been saved
                    for this block;
     5) close_file - ends the use of a file

     For each file that you want to save variables in, you use a process
similar to the following.  First, open the file with open_file.  Then, for
each variable, declare its name, data type, number of values saved per block,
and default value with the def_variable routine.  These two routines set up
the file so that data can be saved and don't get called again for this file.
Next, save the values of variables with save_variable.  When all values
of a block of file variables have been saved, call end_block.  Repeat the
process of saving variables and ending a block for as much data as you want to
save.  After saving the last block, close the file with close_file. 

     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 write error routines
are provided to turn the return value into an error message.


3.1  Description of the Disk Write Routines

3.1.1  Open File Routine:

     file_id = open_file ( filename, open_type )

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

     This routine opens the file "filename" so that data may be written to it.
The parameter "open_type" specifies the following:
     1 - Open the file unconditionally.  Discard any prior data in the file.
     2 - Append to an existing file.
     3 - Open a new file.  If the file already exists, don't open it.
         (An error message will indicate that the file already exists.)

     The data will be written to a file named "filename.sg_data" and
information about this file's format will be written to "filename.sg_format".
Since the variable definition process determines part of the file format
information, the format file is not written until this process terminates
(with the first call to end_block, described below).  When appending to an
existing file, the current format must match that of the appended file.  This
is checked in the first call to end_block. 

Returned value:

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

The following errors are detected:

     - file "filename" is already open
     - filename is too long
     - the number of files currently open is the maximum
     - could not create a format file
     - could not create a data file
     - could not open filename.sg_format for reading
     - could not open filename.sg_data for writing
     - file "filename" exists and open_type prohibits overwriting
     - invalid open_type


3.1.2  Define Variable Routine:
     
     var_id = def_variable ( file_id, name, type, number, def_val )

       argument  |  C type  |  FORTRAN type
     ------------+----------+----------------
       file_id   |   int    |   integer*4
         name    |  char *  |  character*16  (or shorter)
         type    |   int    |   integer*4
        number   |   int    |   integer*4
       def_val   | "type" * |     "type"     (see description below)

     This routine defines parameters of a variable to be saved.  The
parameters are the variable's name, data type, number per block, and default
value.  Variables in a particular file may be defined until the first call to
end_block for that file; i.e. calling end_block ends the variable definition
process for a file.  The string used as the variable's name does not have to
be the name the calling program uses to reference the variable's values.  It
can be some other string of the programmer's choosing.  This name is used to
select the variable for reading by the disk read routines.  It is also used to
select and label variables in SUNGRAPH.  This routine does NOT check for
duplication of variable names, so be sure that each file variable has a unique
name.  The default value is written if the user has saved fewer than "number"
values per block when end_block is called.  In FORTRAN, the default value's
type must be the saved variable's type.  (e.g.  If type=3, the default value
must be a real*4.)  In C, the default value is a POINTER to a value of the
type specified in the argument list.  (e.g.  If type=3, the default value must
be a pointer to a float.)  The argument "type" refers to data types according
to the following table: 

    TYPE  #  |  C TYPE  |  # of BYTES  |  FORTRAN TYPE
    --------------------------------------------------
       1     |  short	|      2       |  integer*2
       2     |   int	|      4       |  integer*4
       3     |  float	|      4       |    real*4

Returned value:

     When no error occurs, the returned value is a variable id which is used
to identify this variable when saving its values with the save variable
routine.  A valid variable id is >= 0.  If an error occurs, the returned value
is < 0. 

The following errors are detected:

     - 'file_id' is out of range
     - 'file_id' corresponds to an unopened file
     - the file variables have already been defined
     - invalid data type specified
     - invalid number of values specified
     - the maximum number of variables have already been defined
     - variable name is too long