celp_3.2a.tar.gz_celp_celp matlab_celp_3.2a.tar.gz

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 er