Click above to get retro games delivered to your door ever month!

     NANFOR.LIB Working Group                         G. Scott [71620,1521]
     Overview                                                          UCLA
     Version 2.1                                              October, 1992

                        THE NANFORUM TOOLKIT (NANFOR.LIB)
            PUBLIC DOMAIN USER SUPPORTED CA-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 Computer Associates CA-Clipper, version 5.01a, 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 forum
               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 was a first step toward organizing
               such an endeavor.

               Release 1.0 of the toolkit was made available in April, 1991
               and had nearly 150 functions.   By the time version 2.0 was
               released in August, 1991, the 1.0 library had been
               downloaded nearly 700 times by CompuServe users.  By October
               of 1992, release 2.0 had been downloaded over 2100 times.
               The source code had been downloaded nearly 1500 times. In
               addition, release 2.0 was placed on the massive Internet
               archive site called SIMTEL20 where it was downloaded by CA-
               Clipper users worldwide.  Over the course of the year that
               release 2.0 was available, seven patches were issued, each
               one gathering nearly 1000 downloads.

               Computer Associates International, Inc. acquired Nantucket
               in the summer of 1992 and subsequently renamed NANFORUM to
               simply CLIPPER.  In addition, the Clipper product itself was
               renamed to CA-CLIPPER. Despite the name changes, forum
               members decided to keep the toolkit's name as "The Nanforum
               Toolkit," partly for nostalgia.  References to NANFORUM in
               this RFC have been replaced with CLIPPER.

          1.2  Trademarks

               CA-Clipper is a registered trademark of Computer Associates
               International, Inc.  Computer Associates will be referred to
               as CA throughout this document.

          1.3  Relationship to CA and third party

               NANFOR.LIB is a project independent of any third party
               developer or CA.  There is no official "sanction" or "seal
               of approval" from CA 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 CA product.

               It is desired that NANFOR.LIB not compete with third party
               products but rather fill in the holes in CA-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 CA-Clipper
               people.  Perhaps even CA employees will contribute.  No one
               is excluded or included due to any particular affiliation.

               CA employees submitting functions are doing so as
               individuals, and are not making a policy of involving CA in
               the project, nor are they committing CA to supporting the
               public domain library.

          1.4  CA-Clipper version supported

               NANFOR.LIB functions, no matter what language they are
               written in, will be designed to work with CA-Clipper version
               5.01a and later.  Many of the functions, particularly those
               that use the EXTEND system, will be compatible with the
               Summer 1987 version of CA-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
               should 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 can 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.  This is encouraged, 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 CLIPPER Forum.

               2.2.1     Contents

                         The deliverables that make up 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   NFINQ.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 format, as well as a
                              WordPerfect 5.1 format copy of NANFOR.RFC
                              named NFRFC.TXT (ASCII) and NFRFC.WP5
                              (WordPerfect 5.1).

                    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)

                    2.2.1.6   PATx.ZIP

                              These are patch files (see paragraph 4.5.1).


     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
               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
               quality of the library's source code shall be encouraged and
               will take place in the proper message section of the
               CompuServe CLIPPER forum.

     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 one, but preferably two, referees.

               Code not meeting the documentation or source code formatting
               standards will generally be returned to the author with
               instructions.

               Referees will test the submitted code.  When the referees
               have finished evaluating a submission, they will report
               their approval or disapproval to the librarian, with
               comments.

               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.  Because this is a
               volunteer project, and because of the complexity involved in
               coordinating testing, documentation, and delivery, there
               will be no fixed interval for updates.

          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
               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 date
               stamp corresponding to the day it is released on the CLIPPER
               forum.  The file time stamps 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 the CLIPPER forum.
               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 <n> 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

               Technical support will work just as any technical subject on
               the CompuServe CLIPPER forum 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 CA-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.

               The librarian is not responsible for testing every possible
               linker for NANFOR.LIB compatibility.  It is hoped that
               linker users will submit appropriate link scripts or other
               documentation for posting in the appropriate section on the
               CLIPPER forum.

          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.

                            (continued in part 2...)