PC Media 4

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 4 / PC MEDIA CD04.iso / share / prog / res104 / res.doc < prev next >

Wrap

Text File | 1994-08-30 | 23.3 KB | 515 lines

RES version 1.04 Documentation 30 August 1994 RES software and manual are Copyright (c) 1993-1994 by Matthew Hildebrand. All rights reserved. Topics covered in this document: ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ INTRODUCTION TERMS OF USAGE AND DISTRIBUTION WHY REGISTER? PACKING LIST USING RES.EXE, THE RESOURCE MANAGER USING RES IN A PROGRAM THE RES FUNCTION LIBRARY ADDITIONAL FEATURES IN THE REGISTERED VERSION CONTACTING THE AUTHOR OBTAINING THE NEWEST VERSION OF RES TROUBLESHOOTING LEGAL STUFF INTRODUCTION ▀▀▀▀▀▀▀▀▀▀▀▀ RES is a package designed to allow C++ developers to use resource files in their programs. A resource file is a file which contains several or many files, each of which is easily accessible by a program through a resource manager interface. The advantages of storing data files this way are that, in a typical program, the files may be accessed more quickly and less disk space will be wasted. Using resource files also makes programs look more professional. The RES package includes the RES.EXE resource manager program, which allows adding, extracting, deleting, and listing of files in resources. The RES package also includes all the source code necessary to access data stored in resources from within your own programs. TERMS OF USAGE AND DISTRIBUTION ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ RES is not free; it is distributed on a "try before you buy" basis. Permission is granted to use RES, for evaluation purposes only, for a trial period of up to 30 days. In order to use RES after the trial period, you MUST REGISTER; registration entitles you to free upgrades, technical support, royalty-free distribution rights for all software written using RES, and a copy of the registered version of RES, which includes complete source code. Failure to register constitutes theft and is punishable by law. By registering a copy of RES, you signify that you have read and understood the terms of usage and distribution explained in this document, and that you agree to be bound by these terms; you also signify that you agree to release the Author (Matthew Hildebrand) from all liability associated with the use of RES. In order to register a copy of RES, send $15 US funds or $20 Canadian funds to Matthew Hildebrand at the address listed in the CONTACTING THE AUTHOR section of this document. Payment by money order, cheque, or cash is acceptable; currency must be US or Canadian funds. Users outside the USA and Canada, please ensure that cheques are drawn on a US or Canadian bank, and that money orders are international if necessary. Also, please send a filled out copy of ORDER.FRM with your payment. Thank you in advance for registering RES; your support is what makes its continued growth possible. Upon receipt of your registration, I will mail you a copy of the registered version of RES, which includes complete source code; this registered copy of RES may not be distributed in any way. Once I have mailed you a copy of the registered version, you will be considered a registered user. If you are interested in receiving notifications of new versions as they are released, or copies of the new versions themselves, refer to paragraph two of the OBTAINING THE NEWEST VERSION OF RES section. The privileges granted by purchasing RES may be retracted if the copyright notice in RESOURCE.CPP (copyright[]) is modified or removed, if any or all of the registered version of RES is distributed in any way, or if any or all of RES's source code is distributed as part of a software package. The shareware version of RES may be distributed freely as long as the distributed package is complete and its contents are not modified in any way, and the distributed package is not sold for profit. WHY REGISTER? ▀▀▀▀▀▀▀▀▀▀▀▀▀ You will receive complete source code for the library. The source includes a complete file manipulation class, which would be useful in many programs. Programs built with RES will be able to create resources, as well as open existing ones. You will be legally entitled to use RES in as many programs as you want, without royalties. You will be entitled to free upgrades, technical support, and eternal happiness. You will have the satisfaction of supporting a good product. PACKING LIST ▀▀▀▀▀▀▀▀▀▀▀▀ The current version of RES consists of the following files: \RES\ <DIR> RES.DOC RES documentation. RES.EXE RES resource manager. REVISION.HST Revision history. CATALOG.TXT Catalog of my software packages. ORDER.FRM Order form (shareware version only). README.NOW Important information. FILE_ID.DIZ Archive description file used by some bulletin board systems (shareware version only). \RES\SOURCE\ <DIR> ERROR.H Error reporter header. FILE.H File class header. PORTABLE.H Portability header. RESOURCE.H Resource class header. (The licensed version contains complete source code.) \RES\LIB\ <DIR> BCL.BAT Borland C++ large model batch file. BCL.MAK Borland C++ large model makefile. BCH.BAT Borland C++ huge model batch file. BCH.MAK Borland C++ huge model makefile. GNU.BAT GNU C++ batch file. GNU.MAK GNU C++ makefile. GENERAL.BAT General batch file. GENERAL.MAK General makefile; edit to suit other compilers. BCL.LIB Borland C++ large model library. BCH.LIB Borland C++ huge model library. GNU.A GNU C++ library. USING RES.EXE, THE RESOURCE MANAGER ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ RES includes a simple resource file manager, RES.EXE. This program can add, delete, extract, and list files in resource files. RES.EXE has a simple, case-insensitive command-line syntax: RES <command> <resource_name> [<file_names>...] <command> must be 'A' (add), 'D' (delete), 'E' (extract), or 'L' (list). <resource_name> is the filename of the resource; the .RES extension is assumed if none is present. If there is an error in the command line, a brief help screen is displayed. Some examples follow: res a foo graphics\*.* res D bar *.obj res a foobar.res tom.* dick?.pcx d:\someprog\miscdata\harry*.* res l foo *.txt res e bar.res *.cpp *.c *.h Resource files created with RES.EXE may be accessed using a simple interface. How to use RES in a program is detailed in the next two sections. USING RES IN A PROGRAM ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ IN ORDER TO USE RES WITH BORLAND COMPILERS, YOU **MUST** DISABLE THE "FAR VIRTUAL TABLES" OPTION (-Vf- FROM THE COMMAND LINE) AND THE "UNSIGNED CHARACTERS" OPTION (-k- FROM THE COMMAND LINE). IF YOU DO NOT, YOU WILL GET LINKER ERRORS. Before using RES for the first time, you should locate the library suitable for use with your compiler; libraries may be found in the LIB directory. Following is a list of libraries and the compilers with which to use them: BCL.LIB Borland C++ large model. BCH.LIB Borland C++ huge model. GNU.A GNU C++. RES has only been compiled for Borland C++ and GNU C++, simply because these are the only C++ compilers I own. Now, to use the RES resource management function library, all you must do is ensure that (a) you #include the RESOURCE.H file (in the SOURCE directory) in any module which uses these functions, and that (b) you link the appropriate library during the linking stage. IF YOU ARE USING A BORLAND COMPILER, BE SURE TO ONLY LINK OBJECT FILES WHICH WERE COMPILED WITH THE "FAR VIRTUAL TABLES" AND "UNSIGNED CHARACTERS" OPTIONS DISABLED. ATTEMPTS TO LINK MODULES COMPILED WITH EITHER OF THESE OPTIONS ENABLED WILL RESULT IN LINKER ERRORS. IN ORDER TO DISABLE THESE OPTIONS, USE THE -Vf- AND -k- COMMAND LINE PARAMETERS, OR USE THE IDE'S OPTIONS->COMPILER MENU. THE RES FUNCTION LIBRARY ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ A description of each of the resource management functions, implemented through the Resource class, follows: Function: Resource::open Purpose: Open a resource. Syntax: int Resource::open(char *filename); Parameters: The resource 'filename' will be opened. Remarks: The shareware version of RES does not allow this function to create new resources; it can only open existing resources created by RES.EXE. Returns: Returns 0 on error. See also: None. Function: Resource::add Purpose: Add a file to the resource. Syntax: int Resource::add(char *filename); Parameters: The file 'filename' will be added. Remarks: - For speed considerations, the file will not actually be added to the resource file until Resource::pack() is called; this may be done either explicitly or automatically by the Resource class destructor. A record of the addition will be made, but since the file is not actually added, it is important to ensure that, until Resource::pack() is called, the stated file is not deleted and that no attempt is made to access it through the resource. - If the file already exists in the resource, it will be overwritten. Returns: Returns 0 on error. See also: None. Function: Resource::del Purpose: Delete a file from the resource. Syntax: int Resource::del(char *filename); Parameters: The file 'filename' will be deleted from the resource. Remarks: For speed considerations, the file will not actually be deleted from the resource file until Resource::pack() is called; this may be done either explicitly or automatically by the Resource class destructor. Returns: Returns 0 on error. See also: None. Function: Resource::extract Purpose: Extract a file from the resource. Syntax: int Resource::extract(char *filename, char *outputPath=NULL); Parameters: The file 'filename' will be extracted into the current directory if 'outputPath' has its default value of NULL; if it has a different value, the string it points to will be prepended to the name of the file, and the resulting string will be used as the name of the output file. For example, if 'outputPath' points to "D:\", then FILENAME.EXT will be extracted to D:\FILENAME.EXT. Note that the trailing backslash in the path is necessary. Remarks: If the file exists, it will be overwritten. Returns: Returns 0 on error. See also: None. Function: Resource::load Purpose: Load some or all of a file from the resource. Syntax: void _far *Resource::load(char *file, void _far *buf=NULL, biguint numBytes=0, bigint startOff=-1); Parameters: Based on other parameters, some or all of 'file' will be loaded. 'startOff' determines the offset into the file of the first byte to load. As with the standard FILE*s, the current offset into each file is maintained; the default value of -1 will cause the use of the current offset, or an offset may be explicitly stated. 'numBytes' determines how much data will be loaded; the default of 0 will cause the loading of all data from 'startOff' to end-of-file, or a value may be explicitly stated. 'buf' determines the address into which the data will be loaded; the default value of NULL will cause a block of memory of the correct size to be allocated (remember to free it later), or an address may be explicitly stated. Remarks: - This function can be confusing; see the examples below. - If this function is instructed to allocate a new buffer, and the allocation fails, then the program will exit. Licensed users may change this behaviour. Returns: Returns NULL on error, or the address of the loaded data on success. See also: None. Examples: // Load all of FOOBAR.DAT into a new buffer addr = res.load("foobar.dat"); // Load all of FOOBAR.DAT into an old buffer res.load("foobar.dat", addr); // Load the first kb of FOOBAR.DAT into an old buffer res.load("foobar.dat", addr, 1024); // Load the second kb of FOOBAR.DAT into a new buffer addr = res.load("foobar.dat", NULL, 1024, 1024); Function: Resource::pack Purpose: Update a resource file, implementing any deletions and additions. Syntax: int Resource::pack(void); Parameters: N/A Remarks: This function has no effect if there have been no additions and/or deletions to/from the resource. Returns: Returns 0 on error. See also: None. Function: Resource::rewind Purpose: Reset a file's current offset to beginning-of-file. Syntax: int Resource::rewind(char *filename); Parameters: The file 'filename' will be rewound. Remarks: None. Returns: Returns 0 on error (ie. if the file does not exist in the resource). See also: Resource::seek() Function: Resource::seek Purpose: Reset a file's current offset to a specified value, fseek()-style. Syntax: int Resource::seek(char *filename, bigint offset, int whence); Parameters: The current offset of 'filename' will be changed. 'whence' determines the point from which the offset will be reckoned; use SEEK_SET (0) for file beginning, SEEK_CUR (1) for current position, or SEEK_END (2) for end-of-file. The pointer will be moved to a position which is 'offset' bytes from the location given by 'whence'; 'offset' may be negative. Remarks: This function is used in the same way as fseek(). Returns: Returns 0 on error. See also: Resource::rewind() Function: Resource::fileSize Purpose: Return the size of a file in the resource. Syntax: biguint Resource::fileSize(char *filename); Parameters: The size of 'filename' will be returned. Remarks: None. Returns: Returns 0 on error, or the size of the file on success. See also: None. Function: Resource::exists Purpose: Return a flag indicating whether or not the resource exists on disk, or whether it is newly created and Resource::pack() has not yet been called to write it to disk. Syntax: int Resource::exists(void); Parameters: None. Remarks: None. Returns: Returns 0 if the resource does not exist on disk, or non-zero if it does. See also: None. Function: Resource::status Purpose: Returns an indication of how many errors have occurred in accessing the resource. Syntax: int Resource::status(void); Parameters: None. Remarks: None. Returns: Returns the number of errors which have occurred in accessing the resource since the last call to this function or the opening of the resource, whichever is most recent. See also: None. ADDITIONAL FEATURES IN THE REGISTERED VERSION ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ In addition to technical support and usage rights, registered users may use the registered version of RES. Not only does the registered version of RES include complete source code for the RES library, it also includes a feature not available in the shareware verion: Programs built with RES will be allowed to create resources, as well as opening existing resources created with RES.EXE. In order to allow creation of resources, comment out the definition of NO_CREATE on line 16 of RESOURCE.CPP, then recompile the library using the appropriate batch file in the LIB directory; uncommenting the line and recompiling will once again cause RES to not create resources. CONTACTING THE AUTHOR ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ I would appreciate hearing any questions, comments, bug reports, or suggestions for improvement. If you have any, feel free to contact me; I can be reached via any of the methods below. When reporting bugs, please be sure to mention the version of RES to which you are referring. Snail mail: Matthew Hildebrand 4 College St. St. Catharines, ON Canada L2R 2W7 Fidonet mail: 1:247/128.2 Please do not post personal messages to me in any of the Fidonet echos, such as C_ECHO or C_PLUSPLUS; such messages are off-topic and liable to annoy the moderator and other echo participants. Use netmail instead. If I find any such personal messages in Fidonet programming echos, I reply by netmail only. If the matter being discussed would be of interest to other echo participants, I will reply in that echo. Internet mail: Matthew.Hildebrand@p2.f128.n247.z1.fidonet.org Internet-Fidonet mail routing sometimes goes awry; if you don't get a reply from me after a reasonable amount of time, send the message again. If you still don't receive a reply, either persist until you do or contact me via a different method. BBS: (905)-935-6628 I am not the sysop of idiot savant BBS, but I will receive messages left there for me. The BBS runs a 14400 bps V.32bis modem. Telephone: (905)-687-8736 Please keep in mind the time zone difference, if any, when calling; I'm in Eastern Standard Time. OBTAINING THE NEWEST VERSION OF RES ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ The most recent distributed copy of RES is available via first-call download from (905)-935-6628 (14400 bps V.32bis), or via file request from Fidonet node 1:247/128 (14400 bps V.32bis) using the magic file name "RES"; unlisted nodes and points are welcome. RES is also distributed through the Fidonet file echo PDNCEE. If, after you have registered, you are interested in receiving new versions of RES as they are released, an easy method is now available. For $3 per mailing (to cover the disk, envelope, and postage), I will mail copies of new versions as they are released, on either a 3.5" or a 5.25" disk. The $3 per mailing may be included with the initial registration fee, with instructions to mail newer versions as they are released, or mailed later with a request for a copy of the newest version. Please ensure that the $3 is paid in either US or Canadian funds; payment by cash, money order (use an international money order if necessary), or cheque drawn on a US or Canadian bank is acceptable. Alternatively, it is possible to receive notifications of updates but not the updates themselves. For $1 per mailing (to cover the envelope and postage), I will mail notifications of new versions when they are released. The $1 per mailing may be included with the initial registration fee, with instructions to mail notifications as new versions are released, or mailed later with similar instructions. Again, please ensure that the $1 is paid in either US or Canadian funds; payment by cash, money order (use an international money order if necessary), or cheque drawn on a US or Canadian bank is acceptable. TROUBLESHOOTING ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ Q. My Borland linker is giving me error messages. What's happening? A. IN ORDER TO USE RES WITH BORLAND COMPILERS, YOU **MUST** DISABLE THE "FAR VIRTUAL TABLES" OPTION (-Vf- FROM THE COMMAND LINE) AND THE "UNSIGNED CHARACTERS" OPTION (-k- FROM THE COMMAND LINE. IF YOU DO NOT, YOU WILL GET LINKER ERRORS COMPLAINING THAT CERTAIN CLASS MEMBER FUNCTIONS CANNOT BE FOUND. LEGAL STUFF ▀▀▀▀▀▀▀▀▀▀▀ RES and its documentation are Copyright (c) 1994 by Matthew Hildebrand. All software and documentation associated with RES is provided "as is": ie., it is provided without warranty of any kind, not even an implied warranty of merchantability or fitness for any purpose. The Author (Matthew Hildebrand) disclaims all warranties, both express and implied, including but not limited to warranties regarding RES's merchantability or fitness for any particular purpose. The author may not be held liable for any damage or misfortune related to the use of this software. Any usage of any or all of RES is done entirely at the user's risk. All registered trademarks in this document belong to their respective owners. End of document.