NANFOR.LIB Working Group G. Scott [71620,1521] Request for Comments UCLA Version 1.0 April, 1991 THE NANFORUM TOOLKIT (NANFOR.LIB) PUBLIC DOMAIN USER SUPPORTED CLIPPER FUNCTION LIBRARY 1 INTRODUCTION This is a standard for establishing and maintaining NANFOR.LIB, a public-domain, user-supported library of functions designed to interface with Nantucket Clipper, version 5.0, and later. You are encouraged to read it over and forward comments to Glenn Scott, CIS ID [71620,1521]. 1.1 History In October and November of 1990, a discussion on the evolution of third-party products, vendors, and marketing took place on the CompuServe Information Service's Nantucket Forum (NANFORUM). During this discussion, a NANFORUM subscriber named Alexander Santic suggested the idea of a user-supported Clipper function library, available to all on the CompuServe Information Service (CIS). A number of subscribers, including several Clipper third party developers, and some Nantucket employees, expressed their support. This standard is a first step toward organizing such an endeavor. 1.2 Trademarks Clipper is a registered trademark of Nantucket Corporation. 1.3 Relationship to Nantucket and third party NANFOR.LIB is a project independent of any third party developer or Nantucket Corporation. There is no official "sanction" or "seal of approval" from Nantucket of any kind. In addition, NANFOR.LIB routines will be accepted and included without regard for whether or not routines performing a similar function are included in a commercial third party or Nantucket product. It is desired that NANFOR.LIB not compete with third party products but rather fill in the holes in Clipper's standard library. However, there will be some overlap into commercial third-party library functions, so it would be best if this is never taken into consideration when deciding on including a particular function. Developers submitting NANFOR.LIB routines can and will be corporate developers, third party developers, independent consultant / programmers, hobbyists, and other Clipper Scott [Page 1] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit people. Perhaps even Nantucket employees will contribute. No one is excluded or included due to any particular affiliation. Nantucket employees submitting functions are doing so as individuals, and are not making a policy of involving Nantucket in the project, nor are they committing Nantucket to supporting the public domain library. 1.4 Clipper version supported NANFOR.LIB functions, no matter what language they are written in, will be designed to work with Clipper version 5.0 and later. Many of the functions, particularly those that use the EXTEND system, will be compatible with the Summer 1987 version of Clipper. However, ensuring Summer 87 compatibility will be the responsibility of the user. If a user wants a function to work with Summer 87, she will have to modify the code herself if necessary. In many cases, this is a trivial task. 1.5 Queries from new users Queries from new users interested in finding NANFOR.LIB will be handled in a uniform and courteous way. A short text file will be created that will briefly explain NANFOR.LIB, who the current people maintaining it are, and how to get a hold of it. This text message will be sent in response to any query. TAPCIS users will find this method very easy to implement. 2 DISTRIBUTION 2.1 Public Domain NANFOR.LIB, its source code, and documentation will be public-domain software. It is not for "sale", and shall not be sold. No fee or contribution of any kind will be required for anyone wanting a copy, other than what they would normally pay to download it from CompuServe. Users will be encouraged to submit functions via CompuServe. 2.2 Official repository It is possible that copies of NANFOR.LIB will be downloaded and distributed elsewhere. That is all right, but the only copy of NANFOR.LIB and all associated documentation that will be maintained by volunteers is in an appropriate library on the CIS Nantucket Forum. Scott [Page 2] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit 2.2.1 Contents The nature of the official posting on CompuServe shall be: 2.2.1.1 NFLIB.ZIP This will contain the files NANFOR.LIB (library), and NANFOR.NG (Norton Guide). 2.2.1.2 NFSRC.ZIP This will contain all the library source code, makefile, and other source-code related materials. 2.2.1.3 FTINQ.TXT This is a short text file used as a response to new user queries (see paragraph 1.5) 2.2.1.4 NFRFC.ZIP This contains an ASCII copy of NANFOR.RFC (this document) named NFRFC.TXT. 2.2.1.5 NFHDRS.ZIP This contains templates of the file and documentation header blocks, including a sample, for prospective authors (FTHDR.PRG, FTHDR.ASM, FTHDR.SAM) 3 POLICY ON INCLUDING FUNCTIONS 3.1 "Best Function" It is possible that more than one developer will submit a function or package of functions that perform substantially the same services. In that event, the referees will choose one to be included based on power, functionality, flexibility, and ease of use. Due to the cooperative, non-commercial nature of the library, no one's feelings should be hurt by excluding duplicate functions. In addition, it is possible that two substantially similar functions or packages will benefit from merging them together to provide new functionality. This will be the Scott [Page 3] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit prerogative of the referees (see paragraph 6.3), in close consultation with the authors. 3.2 Public Domain Each author submitting source code must include as part of that code a statement that this is an original work and that he or she is placing the code into the public domain. The librarian (see paragraph 6.1) and referees should make a reasonable effort to be sure no copyrighted source code, such as that supplied with some third party libraries, makes it into NANFOR.LIB. However, under no circumstances will the librarian, referees, or any other party other than the submitter be responsible for copyrighted code making it into the library accidentally. 3.3 Source code Full source code must be provided by the author for every routine to be included in NANFOR.LIB. No routine, no matter what language, will be put into the library on the basis of submitted object code. 3.4 Proper submission Due to the volume of submissions expected, librarians and referees may not have the time to fix inconsistencies in documentation format, function naming, and other requirements. Therefore, the librarian shall expect source code to arrive in proper format before proceeding further with it. 3.5 Quality and perceived usefulness In a cooperative effort like this, it is very difficult to enforce some standard of quality and/or usefulness. For example, a package of functions to handle the military's "Zulu time" may be very useful to some, and unnecessary to others. The Nanforum Toolkit will by its very nature be a hodgepodge of routines, some of very high quality, some not so high. It is up to the users to improve it. It will be complete in some areas and vastly inadequate in others. It is up to the users to fill in the holes. We shall err on the side of including "questionable" functions, provided they seem to work. Debates on the Scott [Page 4] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit quality of the library's source code shall be encouraged and will take place in the proper message section of NANFORUM. 4 LIBRARY MAINTENANCE PROCEDURE 4.1 Selection procedure Source code will be submitted to the librarian, the documenter (see paragraph 6.2), or one of the referees. Code will be added if it has been reviewed, and approved by at least two referees. Code not meeting the documentation or source code formatting standards will generally be returned to the author with instructions. When the referees have finished selecting a function, they will compile it and submit both source and .OBJ to the librarian who shall add the .OBJ(s) into the library. Every effort should be made to make sure that the C and ASM functions are reviewed by referees with suitable C and ASM experience. 4.2 Update interval As new functions are submitted, they will added to the library, and the documentation updated. However, the library will only be updated at a fixed interval. This interval is currently set at: QUARTERLY. After the initial release, updates occur on or around April 1, July 1, October 1, January 1, etc. Of course, these dates are never guaranteed, and there is always an honorary release date of September 15, which will always be missed. If there are some very important functions that have been added, and the next update interval is, say, two months away, the librarian, documenter, and referees will release a maintenance update anyway, regardless of update intervals. 4.3 Version control NANFOR.LIB will use a numeric version number as follows: The major version will be numeric, starting from 1. This will change with each quarterly update. The minor version will change with each bug fix. This will start with zero Scott [Page 5] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit and continue until the next major update, at which point it will revert to zero again. Typical version numbers might be 1.1, 2.12, 15.2, etc. The .LIB file, and all associated files, will carry a day/time stamp of the first day of the particular release's quarter. The file date shall correspond to the version number (i.e., 1:03am is version 1.3). 4.4 Announcing updates As the library and its associated documentation are updated, simple announcements will be posted on NANFORUM. This is the only place where an update shall be announced. An update will be announced after it has been successfully uploaded to the appropriate library on CompuServe. 4.5 Bug reports and fixes The librarian will correlate and verify all bug reports, with the help of the referees. If the referees believe a bug to be serious, they will fix it and the librarian will release a maintenance upgrade immediately. If they consider it a minor bug, they will fix it but wait for the next scheduled upgrade to release it. In this case, a bug fix may be released as a "Patch." 4.5.1 Patches A "patch" is simply an ASCII text file containing instructions for editing the source code to a misbehaving function or group of functions. Patches may appear in the CIS library before a maintenance release or quarterly upgrade. A patch file will have a name of the form PATn.ZIP where is a number starting from 1. Patches will be numbered sequentially. Patches will be deleted every time a new version of NANFOR.LIB goes on-line. A patch zipfile may optionally contain .OBJ files to be replaced in user libraries via a LIB utility. 4.6 Technical Support Scott [Page 6] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit Technical support will work just as any technical subject on NANFORUM works. Users will post questions and suggestions to a particular message area or thread, and anyone who knows the answer should respond. No one is obliged to answer, but it is considered good form to respond with something, even if one doesn't know the answer. Support will include help on recompiling the routines or modifying the source. 4.7 Linker Compatibility In order to assist users of Clipper third party linkers (such as WarpLink or Blinker), NANFOR.LIB may need to broken up into root and overlay sections. How this will be done will be determined when splitting becomes necessary. 4.8 Splitting NANFOR.LIB by functional category It is possible that at some future date, it will make sense to split NANFOR.LIB into separate functional areas (e.g., video routines vs. date routines, etc). This RFC will be modified accordingly should that need arise. 5 FUNCTION CODING STANDARDS The goal of this standard is not to force anyone to rewrite his code for this library, but to create some consistency among the functions so that they may more easily maintained and understood by all Clipper developers, both novice and advanced. However, it is extremely important that anyone submitting code attach the proper headers and documentation and fill them out correctly. This will make it much easier for code to be added to the library. 5.1 Required sections for each function 5.1.1 Header (author name/etc, version ctrl info) Figure 1 shows a header that must be included at the top of every piece of source code submitted to the library. This header will work with both Clipper and C code. For ASM code, substitute each asterisk ("*") with a semicolon (";") and delete the slashes ("/"). Scott [Page 7] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit /* * File......: * Author....: [CIS: x,x] * Date......: $Date$ * Revision..: $Revision$ * Log file..: $Logfile$ * * * Modification history: * --------------------- * * $Log$ * */ Figure 1 - Standard function header Note that the date, revision, logfile, and modification history fields will be maintained by the librarian and should not be edited or adjusted by code authors. The "File" field shall contain the source file name. This is often independent of the individual function name. For example, a function named ft_screen() would be included in SCREEN.PRG. As a rule, source files (.PRG, .C, .ASM) should not have the "FT" prefix. The "Author" field should have the author's full name, and CIS number. A CIS number is important, as this will make bug fixing and other correspondence easier. 5.1.2 Public domain disclaimer Authors shall simply state "This is an original work by [Author's name] and is hereby placed in the public domain." 5.1.3 Documentation block ( for .DOC, .NG, .TRH ) Scott [Page 8] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit /* $DOC$ * $FUNCNAME$ * * $ONELINER$ * * $SYNTAX$ * * $ARGUMENTS$ * * $RETURNS$ * * $DESCRIPTION$ * * $EXAMPLES$ * * $SEEALSO$ * * $INCLUDE$ * * $END$ */ Figure 2 - Standard Documentation Header The keywords enclosed in dollar-signs delimit sections of the documentation header analagous to those in Nantucket's Clipper 5.0 documentation. Documentation should be written in the same style and flavor as the Nantucket material, if possible. Refer to the Clipper documentation for more detail and numerous examples. The documentation will appear on comment lines between the keywords. Examples are optional. Do not put documentation on the same line as the comment keyword. Note that the $DOC$ and $END$ keywords serve as delimiters. Do not place any text between $DOC$ and $FUNCNAME$, or any documentation after the $END$ keyword, unless that documentation belongs in the source code file and not in the NG/TRH file. Scott [Page 9] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit The $FUNCNAME$ keyword should be followed by the function name, with parentheses, and no arguments or syntax, such as: $FUNCNAME$ ft_screen() Note the indent for readibility. Parentheses shall be added after the function name as shown above. The $ONELINER$ keyword should be followed by a simple statement expressing what the function does, phrased in the form of a command, e.g.: $ONELINER$ Sum the values in an array The length of the entire $ONELINER$ shall not exceed 60 characters (this is a Norton Guide limitation). The $SYNTAX$ keyword should be followed by a Nantucket-standard syntax specifier, such as: $SYNTAX$ ft_screen( [,] ) -> NIL All parameters have proper prefixes (see paragraph 5.4), and are enclosed in . Optional parameters are enclosed in [square brackets] as well. An arrow should follow, pointing to the return value. If there is no return value, it should be NIL. Any others should be preceded with the proper prefix (see the Clipper documentation). The $SEEALSO$ field provides a way to generate cross-references in the Norton Guide help documentation. Use it to point the user to other related functions in the forum toolkit. For example, if ft_func1() is also related to ft_func2() and ft_func3(), the field would look like this: $SEEALSO$ ft_func2() ft_func3() Scott [Page 10] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit Note that fields are separated by spaces and the parentheses are included. The $INCLUDE$ area allows you to specify what files are included by this function (this will be used to organize the on-line help file, and possibly the master makefile). An example would be $INCLUDE$ int86.ch int86.inc Other documenation fields should be self- explanatory. Review the appendix for a sample. All fields are required and must be filled in. Examples should not be considered optional. 5.1.4 Sample header and documentation block Refer to the Appendix for a sample header and documentation block. 5.1.5 Test driver A test driver is an optional section of C or Clipper code that will only be compiled under certain circumstances. Developers are encouraged to include a short "test section" in front of their code. The test driver shall be surrounded by the following pre-processor directives, and placed at the top of the source file: #ifdef FT_TEST [test code] #endif The test driver is currently optional, but authors submitting Clipper code should seriously consider adding it. It is a good way to include short demos within a piece of source code, yet pay no penalty because it is only compiled if needed. It will be invoked when a #define is created that says "#define FT_TEST." This is a way for submitters to include short test routines with their functions and yet keep it all in one source file. This will be useful to end users. Scott [Page 11] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit This test driver may become required in a future version of the RFC. 5.1.6 Code The source code shall be formatted as described in paragraph 5.4. 5.2 Function names All NANFOR.LIB functions start with one of two prefixes. If the function is to be called by user programs, than it will begin with the prefix FT_ ("F", "T", underscore) Note that "FT" is a mnemonic for "Forum Toolkit." If the function is "internal" to a module, then it will be prefixed by an underscore: _FT ( Underscore, "F", "T" ) with no trailing underscore. Examples: FT_CURDIR() "external" _ftAlloc() "internal" 5.3 Librarian's authority to change function names Some functions will be submitted that either (1) bear a similar name to another function in the library, or (2) bear an inappropriate name. For example, a function called FT_PRINT that writes a character to the screen could be said to be named inappropriately, as a name like FT_PRINT implies some relationship to a printer. The librarian shall have the responsibility to rename submitted functions for clarity and uniqueness. 5.3.1 Changing a function name after it has been released Once the library is released with a particular function included, then a function name should generally be frozen and not renamed. To do so would probably cause difficulties with users who had used the previous name and are not tracking the changes to the library. 5.4 Source code formatting Scott [Page 12] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit 5.4.1 Clipper Clipper code shall be formatted in accordance with Nantucket's currently defined publishing standard. Although there will surely be some debate over whether this is a good idea, in general, the goal is to provide something consistent that all Clipper developers will recognize. Minor deviations will be permitted. The Nantucket standard usually means uppercase keywords, and manifest constants, and lower case everything else. In addition, identifiers shall be preceded with the proper metasymbol: n Numeric c Character or string a Array l Logical, or boolean d Date m Memo o Object b Code block h Handle x Ambiguous type Refer to the Clipper documentation for samples of Nantucket's code publishing format. 5.4.2 C C source code shall be formatted in a generally accepted way, such as Kernighan and Ritchie's style used in the book _The C Programming Language_." The use of Nantucket's EXTEND.H is encouraged. 5.4.3 ASM No particular formatting conventions are required for assembly language source code, since assembly code formatting is fairly standard. Lowercase code is preferred. Be sure to include the proper documentation header information, as described above. Scott [Page 13] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit Do not place ASM code in DGROUP. See paragraph 5.12. 5.5 Organization into .PRGs Since many different people will be submitting routines, it is probably best if all routines that belong together are housed in the same .PRG. If there is some reason to split the .PRG, the referees and the librarian will handle that as part of library organization. 5.6 Header files Including a ".ch" or ".h" or ".inc" with each function would get unwieldy. For the purpose of NANFOR.LIB, all #defines, #ifdefs, #commands, #translates, etc that belong to a particular source file shall be included at the top of that source file. Since few submissions will split over multiple source files, there will usually be no need to #include a header in more than one place. If a "ch" file will make the end user's job of supplying parameters and other information to NANFOR.LIB functions easier, then it shall be submitted as a separate entity. The referees will decide on whether to include these directives in a master NANFOR.CH file. 5.7 Clipper 5.0 Lexical Scoping NANFOR.LIB routines that are written in Clipper will make use of Clipper 5.0's lexical scoping features to insulate themselves from the rest of the user's application. For example, all "privates" shall generally be declared "local." If a package of Clipper functions is added to the library, then the lower-level, support functions will be declared STATIC as necessary. 5.8 Use of Publics Authors shall not use PUBLIC variables in NANFOR.LIB functions, due to the potential interference with an end-user's application or vice versa. If a global is required for a particular function or package of functions, that global shall be accessed through a function call interface defined by the author (.e.g, Scott [Page 14] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit "ft_setglobal()", "ft_getglobal()", and so on). Globals such as this shall be declared static in the .PRG that needs them. 5.9 Use of Macros ("&" operator) The use of macros in NANFOR.LIB functions will be, for the most part, unnecessary. Since this is a Clipper 5.0 library, the new 5.0 codeblock construct should be used instead. Anyone having trouble figuring out how to convert a macro to a codeblock should post suitable questions on NANFORUM. 5.10 Use of Static Functions Any Clipper 5.0 function that is only needed within the scope of one source file shall be declared STATIC. This applies mostly to NANFOR.LIB "internals" (names with an "_ft" prefix) that user programs need not access. 5.11 Use of SPI_ interface A common library of low-level routines that are useful in C and assembler functions, called the "Shared Programming Interface", shall be used as a practical alternative to a compiler's standard library, where applicable. These functions were developed by Dirk Lesko and a consortium of third party developers to help reduce the amount of duplicated code pulled in by multiple libraries. SPI.LIB, including its source, is available as a separate library and will always be posted wherever NANFOR.LIB is posted. Use of SPI.LIB will be required if and only if SPI.LIB is widely available in source code form so that authors may see what functions need not be duplicated. 5.12 Use of DGROUP in ASM Functions Use of DGROUP in assembly language functions shall be avoided, in accordance with Nantucket's recommendations. Assembly functions written for NANFOR.LIB shall use a segment named _NanFor, as in the following example: Public FT_ChDir Extrn _ftDir:Far Scott [Page 15] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit Segment _NanFor Word Public "CODE" Assume CS:_NanFor Proc FT_ChDir Far . . . Ret Endp FT_ChDir Ends _NanFor End 5.13 Use of "Internals" Use of Nantucket "internals" by code authors is allowed. However, should any code make use of an internal, i.e., a function or variable that is not part of the published Clipper API, then that internal shall be clearly marked in the documentation (under "DESCRIPTION") and in the actual code, everywhere the internal is used. 5.14 Procedures for compiling functions 5.14.1 Clipper Clipper functions will be compiled under the current release of Clipper 5.0, with the following compiler options: /n /w /l Note that neither line numbers nor debugging information will find its way into NANFOR.LIB, to keep the code size down. End users may recompile NANFOR.LIB with these options enabled if they want to view NANFOR.LIB source in the debugger. 5.14.2 ASM Assembly functions must compile successfully under any MSDOS assembler capable of producing the proper .OBJ file. However, care should be taken not to use any macros or special syntax particular to one vendor's assembler, because that would make it difficult for end users to recompile the source. 5.14.3 C Scott [Page 16] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit C functions must compile successfully under any C compiler capable of interfacing to Clipper. Obviously, Microsoft C, version 5.1, is the preferred development environment. Care should be taken, when writing C code, not to use any special compiler features particular to one vendor's C compiler, because that would make it difficult for end users to recompile the source. 5.15 Functions requiring other libraries It is very easy to write functions in C that call the compiler's standard C library functions. However, NANFOR.LIB can make no assumptions about the end user's ability to link in the standard library or any other library. Therefore, no function will be added to NANFOR.LIB that requires any other third party or compiler manufacturer's library, except for SPI.LIB, described above. 6 ADMINISTRATIVE DETAILS 6.1 Librarian The librarian will the person who physically creates the library via a library utility and uploads it to the proper NANFORUM library on CompuServe. The librarian generally does *not* test code or edit source code to repair formatting errors. 6.2 Documenter The documenter is responsible for maintaining the Norton and/or Tom Rettig guides and keeping it in sync with each new release. 6.3 Referees Referees are volunteers who read source code, clean it up, compile it, look for problems like potentially problematic C code, decide on which function is best, consolidate common functions, etc. They make sure the header and documentation blocks are present. There is no election or term for refereedom. One simply performs the task as long as one can and bows out when necessary. 6.4 Transitions Not everyone will be able to stay around forever to keep working on this project. Therefore, it is the Scott [Page 17] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit responsibility of each referee, documenter, or librarian to announce as far in advance as possible his or her intention to leave, in order to give everyone a chance to come up with a suitable replacement. Don't let it die! 7 CONTRIBUTORS Current contributors, directly and indirectly, to this document include: Don Caton [71067,1350] Bill Christison [72247,3642] Robert DiFalco [71610,1705] Paul Ferrara [76702,556] David Husnian [76064,1535] Ted Means [73067,3332] Steve Kolterman [76320,37] Alexander Santic [71327,2436] Glenn Scott [71620,1521] Keith Wire [73760,2427] Craig Yellick [76247,541] James Zack [75410,1567] Scott [Page 18] RFC: NANFOR.LIB April, 1991 Ver: 1.0 The NANFORUM Toolkit APPENDIX: SAMPLE HEADER AND DOCUMENTATION BLOCK This example shows how you would set up the headers for either a Clipper or C source file. /* * File......: PRTSCR.C * Author....: Ted Means [CIS: 73067,3332] * Date......: $Date$ * Revision..: $Revision$ * Log file..: $Logfile$ * * This is an original work by Ted Means and is placed in the * public domain. * * Modification history: * --------------------- * * $Log$ * */ /* $DOC$ * $FUNCNAME$ * FT_PrtScr() * $ONELINER$ * Enable or disable printscreens. * $SYNTAX$ * FT_PrtScr( ) -> * $ARGUMENTS$ * set to .t. will enable printscreens, .f. will * disable printscreens. * $RETURNS$ * The current state ( .t. for enabled, .f. for disabled). * $DESCRIPTION$ * This function is valuable if you have a need to disable the * printscreen key. It works by fooling the BIOS into thinking * that a printscreen is already in progress. The BIOS will then * refuse to invoke the printscreen handler. * $EXAMPLES$ * FT_PrtScr( .F. ) // Disable the printscreen key * FT_PrtScr( .T. ) // Enable the printscreen key * MemVar := FT_PrtScr() // Get the current status * $SEEALSO$ * ft_peek() ft_poke() * $INCLUDE$ * prtscr.h * $END$ */ Scott [Page 19]