MVG FILE I/O UTILITY ROUTINES by Design aids data services This document describes the mvg file i/o utilitiy routines found in MVGALL.OLB Version as of 31-Jan-85 1.0 Open New Fixed File ____ ___ _____ ____ ********** * fopenc * ********** NAME: fopenc -- Open New Fixed File SYNOPSIS: FILE * fopenc(filnam,recz) char *filnam; /* pointer to the name of the file to open */ unsigned recz; /* record size in the file */ DESCRIPTION: fopenc() creates and opens a fixed length file. 0 is returned on error, $$ferr contains the error code. BUGS: AUTHOR: Machiavelli Systems Page 3 fopenc Open New Fixed File 2.0 Open a Fixed File for Update ____ _ _____ ____ ___ ______ ********** * fopenx * ********** NAME: fopenx -- Open a Fixed File for Update SYNOPSIS: FILE * fopenx(filnam,recz) char *filnam; /* pointer to name of file to open */ unsigned recz; /* record size of file being opened */ DESCRIPTION: fopenx() opens the specified fixed length file for update. The pointer to the file descriptor is returned, of 0 for error. If an error occurs, $$ferr is set. BUGS: AUTHOR: Machiavelli Systems Page 4 fopenx Open a Fixed File for Update 3.0 Fixed Length Get _____ ______ ___ ********* * frget * ********* NAME: frget -- Fixed Length Get SYNOPSIS: int frget(buffer,bufsiz,ioptr,number) char *buffer; /* where to put it */ unsigned bufsiz; /* how much to get */ FILE *ioptr; /* where to get it from */ long number; /* which record to get */ DESCRIPTION: frget() get's a specified record of a specified length from the specified input file, and places it in the buffer. This is a FCS 'C' interface routine. Returns 0 for sucess, or $$ferr on error. See RSX11M I/O error codes. BUGS: Very sleezy, and needs to be re-written. AUTHOR: Machiavelli Systems Page 5 frget Fixed Length Get 4.0 Random Acess Put ______ _____ ___ ********* * frput * ********* NAME: frput -- Random Acess Put SYNOPSIS: int frput(buffer,bufsiz,ioptr,number) char *buffer; /* pointer to output buffer */ unsigned bufsiz; /* size of buffer */ FILE *ioptr; /* output file pointer */ long number; /* record number to write */ DESCRIPTION: frput() puts a record to a fixed length file, at a specified record number. BUGS: AUTHOR: Machiavelli Systems Page 6 frput Random Acess Put 5.0 Get File Size in Bytes ___ ____ ____ __ _____ ********* * fsize * ********* NAME: fsize -- Get File Size in Bytes SYNOPSIS: long fsize(ioptr) FILE *ioptr; /* file to be looked at */ DESCRIPTION: fsize() returns the file size, in bytes, of the specified file. BUGS: AUTHOR: Machiavelli Systems Page 7 fsize Get File Size in Bytes 6.0 Define the File as Random Access ______ ___ ____ __ ______ ______ ********** * ranacc * ********** NAME: ranacc -- Define the File as Random Access SYNOPSIS: int ranacc(ioptr) FILE *ioptr; /* the file to define */ DESCRIPTION: ranacc() sets the random access bits in the file header block, allowing the user to use recnum(). This routine will set the R.FIX bit, when the file is closed. BUGS: AUTHOR: Machiavelli Systems Page 8 ranacc Define the File as Random Access 7.0 Set Record Number ___ ______ ______ ********** * recnum * ********** NAME: recnum -- Set Record Number SYNOPSIS: int recnum(ioptr,number) FILE *ioptr; /* the file to have it's record number set in */ long number; /* the record number to point it at */ DESCRIPTION: recnum() points a file's record pointer at the specified record. ranacc() must have been called before access to the file via this routine can be used (recnum will work, but read/write wont). BUGS: AUTHOR: Machiavelli Systems Page 9 recnum Set Record Number 8.0 Set File Record Size ___ ____ ______ ____ ********** * recsiz * ********** NAME: recsiz -- Set File Record Size SYNOPSIS: int recsiz(ioptr,size) FILE *ioptr; /* pointer to file to be set */ unsigned size; /* what to set the record size to */ DESCRIPTION: recsiz() sets the record size in the file descriptor block. recsiz() doesn't check for a previously set record size. The size set, will stay set in the file, after the file is closed. BUGS: AUTHOR: Machiavelli Systems Page 10 recsiz Set File Record Size 9.0 Get Byte Posn. in File ___ ____ _____ __ ____ ********** * _utell * ********** NAME: _utell -- Get Byte Posn. in File SYNOPSIS: unsigned _utell(fp) FILEP fp; /* file pointer of file to be checked */ DESCRIPTION: _utell() returns an unsigned byte position within the file. The value returned is 0-org byte posn. in file. BUGS: All this does is cast ftell to unsigned. AUTHOR: Machiavelli Systems Page 11 _utell Get Byte Posn. in File 10.0 Close Data Dictionary _____ ____ __________ ******** * zdci * ******** NAME: zdci -- Close Data Dictionary SYNOPSIS: int zdci(ioptr) FILE *ioptr; /* pointer to file descriptor to close */ DESCRIPTION: zdci() closes the data dictionary file pointed to by ioptr. If an error occurs in closing the file, an error message is printed. BUGS: Like a lot of other DLOW routines, this one is the same as a library function. fclose(). AUTHOR: Machiavelli Systems Page 12 zdci Close Data Dictionary 11.0 Open a data dict. File for Read ____ _ ____ _____ ____ ___ ____ ******** * zdoi * ******** NAME: zdoi -- Open a data dict. File for Read SYNOPSIS: FILEP zdoi(name) char *name; /* name of file to open */ DESCRIPTION: zdoi() opens a file, using the standard open, for read. zdoi() returns a FILE *. displays an error if file can't be opened. BUGS: why not use fopen(name,"r") instead AUTHOR: Machiavelli Systems Page 13 zdoi Open a data dict. File for Read 12.0 Read a Line from a File ____ _ ____ ____ _ ____ ********** * zgetli * ********** NAME: zgetli -- Read a Line from a File SYNOPSIS: int zgetline(ioptr,buffer,buflen) FILE *ioptr; /* pointer to file discriptor block */ char *buffer; /* pointer to destination buffer */ unsigned buflen; /* maximum bytes to read into the buffer */ DESCRIPTION: zgetline() gets a line of input from the specified file, leaving no '\n' at the end of the line. zgetline() returns byte position in file, or -1 on error. BUGS: How about fgetss() ? AUTHOR: Machiavelli Systems Page 14 zgetli Read a Line from a File 13.0 Get Fixed Length Record ___ _____ ______ ______ ********** * zinrec * ********** NAME: zinrec -- Get Fixed Length Record SYNOPSIS: int zinrec(fptr,recnum,buf) FILE *fptr; /* pointer to file descriptor */ long recnum; /* record number to be got */ char *buf; /* where record is to be put */ DESCRIPTION: zinrec() gets the specified record from the specified file into a buffer. The number of bytes read in is equil to the file's record size, this means that exactly 1 record is read in. Returns 0 for success, or $$ferr on error. BUGS: AUTHOR: Machiavelli Systems Page 15 zinrec Get Fixed Length Record 14.0 Get uncommented line from file ___ ___________ ____ ____ ____ ********** * znextl * ********** NAME: znextl -- Get uncommented line from file SYNOPSIS: int znextline(fil,inbuf,len) FILEP fil; /* pointer to the file structure */ char *inbuf /* pointer to the destination buffer */ int len; /* maximum bytes to be read */ DESCRIPTION: znextline() gets a line from the specified input file, skips white spaces, and checks for COMMENT_CHAR. If COMMENT_CHAR is the first non-white on the line, a new line is input, and the same done. If an error occurs in reading the file, then ERROR is returned. BUGS: AUTHOR: Machiavelli Systems Page 16 znextl Get uncommented line from file 15.0 Open Any Type Of File Any Mode ____ ___ ____ __ ____ ___ ____ ********* * zopen * ********* NAME: zopen -- Open Any Type Of File Any Mode SYNOPSIS: FILE *zopen(fname,mode,recsiz,err) char *fname; /* name of file to be opened */ char *mode; /* open mode of the file (as above) */ int recsiz; /* record size of the file (as above) */ char *err; /* optional error code string */ DESCRIPTION: char *fname : file name of file to be opened char *mode : open mode for file. Values are: "a" - append [ File is opened for r/w , the record pointer is initialy set to the end of the file. The record size, file format, and if the file exists, is checked. If the file does not exist, then an error code is returned to that effect. ] "r" - read [ File is opened for r/w , the record pointer is initialy set to the begining of the file. The record size, file format, and if the file exists, is checked. If the file does not exist, then an error code is returned to that effect. ] "w" - write [ File is created, the record pointer is initialy set to the begining of the file, and the file header is set up according to the mode of access (see recsiz). If the file already exists, or the file can't be created, an error occurs. ] "t" - trap [ Error Trapping is enabled. This means that on an error, an error code is returned in err, rather than the routine taking things into it's own hands. ] "f" - force [ Force a new version of the file. This means that the open creates a new version of the file, wether or not and old version exists. ] Page 17 zopen Open Any Type Of File Any Mode int recsiz : The record size, in bytes. 0 specifies a stream record. char *err : Optional pointer to string, which the routine returns an error code into, if the trap is specified. Error values are : "n" - File does not exist, or is zero-length. Occurs only on "r" or "a" modes. File is opened in the "w" mode. "l" - File opened, has different record length, than the specified record length. Occurs only on "r" or "a" modes. File is opened, and the reclen of the file is not changed. The file record lengh is returned after the "l". "a" - Bad file attributes, for that mode, ie file opened for fixed length, is steam, or visa versa Occurs only on "r" or "a" modes. File is opened, and the file attributes are not altered. "e" - File already exists. The file to be created, already exists. The file will be opened in the "r" mode. Occurs only on "w" mode. "c" - Conflicting modes. More than one open mode is specified, in the mode string. "r" "w" "a" can't be specified together. If this error occurs, the the file is not opened. "b" - Blank file name. File is not opened. "m" - No open mode was specified in the mode string. Either "r" "w" or "a" has to be specified. "f" - A force mode was specified, without a Write mode. A new version cannot be created, if you are reading, or appending. "s" - System opening error. File could'nt be opened for some reason besides the above. The error can be found in $$ferr. BUGS: AUTHOR: Machiavelli Systems Page 18 zopen Open Any Type Of File Any Mode 16.0 Write a Fixed Length Record _____ _ _____ ______ ______ ********** * zoutre * ********** NAME: zoutre -- Write a Fixed Length Record SYNOPSIS: int zoutrec(fptr,recnum,buf) FILE *fptr; /* file to be written to */ long recnum; /* the record number to put */ char *buf; /* where to get the data from */ DESCRIPTION: zinrec() puts a buffer into the specified record in the specified file. The number of bytes written is equil to the file's record size, this means that exactly 1 record is written. Returns 0 on success, or $$ferr on error. BUGS: AUTHOR: Machiavelli Systems Page 19 zoutre Write a Fixed Length Record 17.0 Close Report Specs. File _____ ______ ______ ____ ******** * zrci * ******** NAME: zrci -- Close Report Specs. File SYNOPSIS: int zrci(ioptr) FILEP ioptr; /* file structure pointer of file to close */ DESCRIPTION: zrci() closes a report specs. file, and displays an error if file is not able to be closed. BUGS: Why not use fclose(ioptr). AUTHOR: Machiavelli Systems Page 20 zrci Close Report Specs. File 18.0 Open a Report Specs. File ____ _ ______ ______ ____ ******** * zroi * ******** NAME: zroi -- Open a Report Specs. File SYNOPSIS: int zroi(name) char *name; DESCRIPTION: zroi() opens a report specs. file for random input. If the file can't be opened, then an error message is printed. BUGS: It only calls zdoi(). This routine exists only so that a different name can be used. It is a waste of room. Why no use fopen(name,"r") AUTHOR: Machiavelli Systems Page 21 zroi Open a Report Specs. File 19.0 Move Record Pointer ____ ______ _______ ********* * zseek * ********* NAME: zseek -- Move Record Pointer SYNOPSIS: int zseek(fp,byte) FILE *fp; unsigned byte; DESCRIPTION: zseek() positions the file's record pointer to a specified position in the file. If the seek failed, then an error message is displayed. For more information look a fseek() in wizard.doc (large manual). BUGS: Another case where a library function only needs casting. zseek(fp,byte) := fseek(fp,(long)byte,0) AUTHOR: Machiavelli Systems Page 22 zseek Move Record Pointer 20.0 Open a Slab File ____ _ ____ ____ ******** * zsoi * ******** NAME: zsoi -- Open a Slab File SYNOPSIS: int zsoi(name) char *name; /* name of file to be opened */ DESCRIPTION: zsoi() openes a slab file for random access read. zsoi() returns FILE *, or 0 if file unable to be opened. BUGS: Why not use fopen(name,"r"). Very similar to zdoi. AUTHOR: Machiavelli Systems APPENDIX A MVGALL INDEX The following is a keyword in context index to the MVG file I/O routines The entry in the left-hand column is the title of the routine in the mvgfio documentation ranacc the File as random access define frput random acess Put zopen open any type of File ranacc define the File as random access _utell get byte posn. in File fsize get file Size in bytes zdci Close data dictionary zrci close report specs. File zdoi open a data dict. File for read zdci Close data dictionary ranacc access define the File as random zdoi open a data dict. File for read zdci Close data dictionary zrci close report specs. File _utell get byte posn. in File zroi open a report specs. File zsoi open a slab File zopen open any type of File zgetli read a line from a File ranacc define the File as random access zdoi open a data dict. File for read fopenx open a Fixed File for update znextl uncommented line from file Get fopenc Open new fixed file recsiz set file Record size fsize get file Size in bytes fopenx open a Fixed File for update zoutre Write a Fixed Length Record zinrec get Fixed length record fopenc Open new fixed file frget fixed length Get frget fixed length Get znextl file Get uncommented line from zinrec get Fixed length record _utell get byte posn. in File MVG File I/O routines Page A-2 MVG File I/O index fsize get file Size in bytes zoutre Write a Fixed Length Record frget fixed length Get zinrec get Fixed length record zgetli read a line from a File znextl Get uncommented line from file zseek move Record pointer fopenc Open new fixed file recnum set Record number fopenc Open new fixed file fopenx update open a Fixed File for zdoi read open a data dict. File for zroi open a report specs. File zsoi open a slab File zopen open any type of File zseek move Record pointer _utell get byte posn. in File frput random acess Put ranacc define the File as random access frput random acess Put zdoi a data dict. File for read open zgetli read a line from a File zoutre Write a Fixed Length Record recnum set Record number zseek move Record pointer recsiz set file Record size zinrec get Fixed length record zrci close report specs. File zroi open a report specs. File recnum set Record number recsiz set file Record size fsize get file Size in bytes recsiz set file Record size zsoi open a slab File zrci close report specs. File zroi open a report specs. File zopen open any type of File znextl Get uncommented line from file fopenx open a Fixed File for update zoutre Write a Fixed Length Record