PC Press 1997 July/Sezamfile97_1.iso/msdos/clipper/nettos11.a01/DOC/INF.DOC

Text File | 1993-07-27 | 23KB | 601 lines

!short: About NETTO
'---------------------------------------------------------------

NETTO is a public domain software library of code written for
CA-Clipper application development language from Computer Associates
Internal, Inc., version 5.2 and above.

NETTO provides access to many of the Novell NetWare application
programming interfaces (APIs).  The APIs are accessed through
either a simple function call, or via a command defined by
the NETTO library.

Please read this on-line documentation before using NETTO to see
if it will be suitable for you.

NETTO comes with source code.  If you did not receive source code
with NETTO, you can find it on CompuServe.

!short: What you can do with NETTO
'---------------------------------------------------------------

You can do a lot.  Assuming you have the appropriate rights, you
can, for example:

    -  Find out what user is running your application
        -  Find out what users are logged in to the server
        -  Ask for a user's NetWare password and verify it
        -  Print directly to NetWare print queues
        -  Attach to servers and log in
        -  Build queue servers and submit queue jobs of any type
        -  Disable login

!short: System and Software Requirements
'---------------------------------------------------------------

NETTO requires CA-Clipper version 5.2 or above.  To use NETTO,
you must also link in the Nanforum Toolkit, version 2.1 or
later.

!short: A Note to Authors
-------------------------

AUTHORS! If I didn't include something you sent me, it could be
because:

    -  What you sent didn't work
    -  I tried to contact you about it and you didn't respond
    -  It required I think about it more than a half hour so
       I put it off (likely)
    -  I forgot about it completely (extremely likely)

I know there are one or two of you who keep reminding me about
the same thing over and over and I can't keep track of it due
to a major cerebral overload that simply causes my brain to
reject additional information once it reaches a certain high
watermark.  When this happens, the only thing I can recall
is my junior high locker combination.  But enough about me.

_Please_ don't be offended.  Just contact me as soon as possible
and we'll try to right things in the next release.

If you're thinking about submitting code; examine the code in
the NETTOS source library, and adhere to the Nanforum Toolkit
standards.

    - Glenn Scott
          CompuServe:  71620,1521
          Internet:    [e-mail]

!short: Installation and Linking
'---------------------------------------------------------------

^bComponents^b

NETTO consists of the following two files:

    NETTOL.ZIP       Library, documentation, .CH files
        NETTOS.ZIP       Source code, makefile

Unzip NETTOL.ZIP to reveal

        NETTO.LIB
        NETTO.CH
        NETTO.NG

^bInstalling the Library^b

Place NETTO.LIB in the directory where your other CA-Clipper
.LIB files are, such as \clipper5\lib.

Place NETTO.CH in the directory where your other CA-Clipper
.CH files, such as \clipper5\include.

Place NETTO.NG in the directory where your Norton Guide
databases are, such as \clipper5\ng.

You're ready to go!

^bInstalling the Source^b

You do not need to install the source to use NETTO.  You
can skip this step if you don't need to examine the source
code now.

Make a subdirectory for the source code; e.g., \netto\src.
Place NETTOS.ZIP in \netto\src.  Unzip NETTOS.ZIP with the
-d option:

    pkunzip nettos -d

and the source code tree will be created.

^bIncluding the .CH file^b

You only need to include the .CH file in your .PRG files if you
make reference to one of the NETTO commands (as opposed to the
functions), or the manifest constants.  If you need to include
NETTO.CH, place a directive at the top of your .PRG as follows:

    #include "netto.ch"

^bLinking^b

If you use NETTO functions, you must include NETTO.LIB and NANFOR.LIB
on your link line:

    RTLINK:

    rtlink fi myapp lib netto, nanfor

    WARPLINK:

    rtlink myapp,,,netto+nanfor

    BLINKER:

    [?]


^bOverlay Considerations^b

Almost all of the NETTO library is Clipper code and can be overlaid.
[To be written]

!short: Compatibility with ExoSpace (TM)
'----------------------------------------

[At release time, a product from SofDesign International and ObjecTech,
Inc. called ExoSpace (tm) was released, which is a DOS Extender
designed to run CA-Clipper applications in protected mode.  A rewrite
of the FT_INT86() function from the Nanforum Toolkit, on which all
of NETTO is based, was required to be compatibile with ExoSpace.
This re-write is well underway and a patch to provide ExoSpace
compatibility should be available soon.]

!short: Is it wise to make a program NetWare-specific?
'---------------------------------------------------------------

[This is something that should be discussed but I didn't have
time to write it.  Perhaps for the next release.]


!short: The NETTO Mailing List!
'-------------------------------

If you have access to the Internet (and this includes CompuServe
users), you can join an experimental mailing list to discuss
Netto issues, ask questions, and report bugs.

To subscribe to the list, you have to send a specially formatted
mail message to a mail server.  Once your subscription is
confirmed, you will receive postings via electronic mail, and
you can post your own.  You may at any time sign off the
mailing list.

^bTo subscribe:^b

Compose a mail message in which the first line of the body of
the message says simply:

    subscribe netto

Then send it to the following address:

    If you're on the Internet:   [e-mail]
    If you're on CompuServe:     >internet: [e-mail]

CompuServe users:  This message must be sent through CompuServe
MAIL (GO MAIL) and it's important that you include the ">" symbol.

In due time you will receive a confirmation via electronic mail with
some additional instructions.

^bTo post messages to the list:^b

Send an electronic mail message to the following address:

    If you're on the Internet:    [e-mail]
    If you're on CompuServe:      >internet: [e-mail]

^bTo sign off the list:^b

Compose a mail message in which the first line of the body of
the message says simply:

    unsubscribe netto

Then send it to the following address:

    If you're on the Internet:   [e-mail]
    If you're on CompuServe:     >internet: [e-mail]

If you're not on CompuServe or the Internet, you may still have an
electronic mail gateway to the Internet.  Ask your local system
administrator, BBS Sysop, electronic mail expert, or customer
service representative.

!short: Encrypted login support
'---------------------------------------------------

When NETTO was written, we included support for encrypted login.
Many of the recent NetWare revisions encrypt the passwords over
the wire when you log in.  The login.exe program contains the
proprietary, secret encryption algorithm.

Novell makes this encryption algorithm available to third parties
in the form of pre-compiled .OBJ files.  These are available to
developers who have signed licensing agreements with Novell, and
can be downloaded from the private Novell developer forum on
CompuServe, called NOVDEV.

We asked Novell if we could include this .OBJ in our release.
They felt that since their encrypted code is their property,
having it appear in a public domain collection would be
inappropriate.  They want all users to be licensed appropriately.

If you want to do encrypted login, you're going to have to be
licensed to do it.  My suggestion is to join Novell's Professional
Developer's Program.  This is free.  (Info on the PDP is available
elsewhere in this Norton Guide, in the "Resources" area.)  Then,
contact Novell's developer support and ask about getting the
encrypted login code.

Note that I believe there are a couple versions of this code.
The latest contains support for Novell's new packet signature
security technology.  We haven't tested with the latest versions
with NETTO.

Perhaps one of you would like to become the expert in this.  I need
some relief from worrying about it.

!short: Legal status
'---------------------------------------------------

When NETTO was being developed, someone suggested our efforts
were somehow `illegal' since we were documenting NetWare API
return codes.

I contacted Novell Legal directly and found this was not a problem,
although they did object to including encrypted login code, so we
removed it.

I have a signed letter on file from a Novell attorney, in case
anyone doesn't believe me.  So there.

!short: Support for protected mode (e.g., ExoSpace)
'---------------------------------------------------

NETTO should work with ExoSpace, provided you link the NANFORX.LIB
library _ahead_ of NANFOR.LIB.  NANFORX.LIB contains a version of
ft_int86() that is compatible with the ExoSpace DOS extender for
Clipper, sold by SofDesign, International.  ft_int86() is called
by every function in NETTO.  NANFORX.LIB is found in NFORX.ZIP,
available in library 5 of the CLIPPER forum on CompuServe.

!short: Credits
'---------------------------------------------------

Librarian:   Glenn Scott [71620,1521]

Contributors:

Gregory Anthony [70045,1160]
Joseph D. Booth [72040,2112]
Sheldon Easterbrook [71421,254]
Michael Landesman [76376,2465]
Steve Larsen [76370,1532]
Ted Means
David A. Minter [76247,3475]
Rodgers Moore [75730,2244]
David Peterson
Mike Taylor, modifications by Ted Means [73310,3013]
Glenn Scott [71620,1521]
Christopher Shortt [72760,3271]
Norbert Sommer [100016,1241]
Kevin Maher/Steve Tyrakowski [73766,1224]

Thanks to all the beta testers, well-wishers, Technicon '92 attendees,
and CA-Clipper third party NetWare library developers.  To Ted Means
for creating FT_INT86(), the key to the whole thing, and for various
other bits and pieces that seem to hold the whole library together.
To Steve Hochschild of Lotus, formerly of Novell Developer Relations,
for the encouragement and software tools.  To Kristin Burkland at
Novell for getting the seal of approval from Novell Legal.  Hearty
thanks to David `Dippy' Peterson, Steve Rowe, and the entire
Australian crew that worked with them for early enthusiasm and
testing; and especially to David for fixing the date code so it
would work internationally.

Most special thanks to Steve Larsen, Steve Tyrakowski, and Kevin Maher,
the core team, who stuck with it.

We welcome your involvement: please contact us via CompuServe at
71620,1521.  Via the internet at [e-mail].
Post questions and comments on the CA-Clipper forum on CompuServe
(GO CLIPPER).

Join the NETTO mailing list!  See elsewhere in this Guide.

Report bugs!  Better yet, fix them!

!short: Getting Support
'-----------------------

Many people believe that because a software package is in the
public domain, it will be unsupported.  This may or not be
the case.

If you need assistance, try the following avenues:

    *  Find another developer that is using the library, and
       ask her

    *  Ask on the BBS or on-line service where you obtained
       the library.  The best place is to ask on the CompuServe
       Clipper forum (GO CLIPPER), where this library has a home.

    *  Subscribe to the new automated NETTO mailing list, and
       ask the question.  There's another section in this Norton
       Guide about the mailing list.

    *  Send an electronic mail message to one of the authors.
       While we cannot guarantee that any particular author will
       be available to support the library, you can always try.
       If you're on CompuServe, the CIS ID that is shown in
       the documentation will suffice.  If you're on the Internet,
       convert the CIS ID from this form:

                        nnnnn,xxx

       to:

                        [e-mail]
                              ^--- note the dot instead of the comma.

    *  Hire a consultant.  Why not?  People hire you, don't they?
       Find some Clipper developer that is familiar with this
       library and pay them to fix or modify it, or otherwise
       show you how to use it.

It is important to realize that you're dealing with Novell NetWare
here, and Novell maintains a heavy presence on the CompuServe
Information Service.  Some of Novell's CompuServe forums you might
be interested in include:

        NOVC           Sections on NetWare programming
        NOVDEV         Private forum for members of developer's program
        NOVUSER        Novell-related files not uploaded by Novell
        NOVLIB         Novell patches and other official uploads
        NOVFILES       Novell patches and other official uploads

!short: Warnings
'---------------

Something can always go wrong.  It is possible that using this
software could, at some point, result in a machine lockup or, more
remotely, a server abend (although in over a year of testing I've
never seen this happen).

These problems could be caused by you or by the software.  It is
important that you always test your code on non-production servers
if possible, and to make sure that you have backups of important
files.  This is just common sense.

!short: Trademarks and Disclaimers
'---------------------------------------------------------------

All products, anmes, and services are trademarks or
registered trademarks of their respective companies.

Novell and NetWare are registered trademarks and Transaction
Tracking System (TTS) and NetWare shell are trademarks of Novell,
Inc.

CA-Clipper is a registered trademark of Computer Associates
International, Inc.

Neither Novell nor Computer Associates is affiliated with this
project in any way.  Neither company provides any support or
other assistance with this project.

This software is in the public domain and is provided AS IS,
with no warranties expressed or implied.  There is no author
or copyright holder for this work.

!short: NETTO's limitations
'---------------------------------------------------------------

Because NETTO isn't a commercial product, we have no need to
gloss over its limitations and problems.  We would appreciate you
pointing them out as well so we can include them here.

   ^bMissing APIS^b

   The most obvious problem with NETTO is that not all the APIs are
   provided.  This is usually because no one volunteered to
   write the code, or the code couldn't be finished in time,
   or because there is some technical reason it won't be easy
   under straight Clipper.

   The best way to solve problems with missing APIs is to offer to
   write code.  Get in touch with any NETTO author and he or she
   will point you in the right direction.

   ^bNetWare Versions^b

    NETTO was written in 1992 and was tested primarily on NetWare 3.x
    although most of the APIs should work on 286 servers. NetWare 4.0
    was being  readied for release at the time NETTO v1.0 was done; only
    limited NetWare 4.0 testing was done.

    ^bNetWare Lite? LanMan? VINES?^b

    NETTO will not work on NetWare Lite, or on networks from other
    vendors such as Banyan VINES or Microsoft Lan Manager.

!short: Bugs and how to report them
'---------------------------------------------------------------

There will probably be bugs.  The best way to get those fixed is to
report them quickly and in such a way as to be useful.  This is
best accomplished by observing facts and reporting them.  Sample
code (provided it's not an entire 200K application but a short
snippet that will fail) is most welcome.

No one will complain if you fix the bug yourself and submit the
edited code.

Post the bug reports and fixes publicly on the CLIPPER forum
on CompuSErve, or e-mail then to 71620,1521 (internet:
[e-mail]).

You can also join the NETTO mailing list to post bug reports!
Check for the section about the mailing list elsewhere in this
guide.


!short: Will all this work under NetWare 4.0?
'---------------------------------------------------------------

If you're planning to upgrade to NetWare 4.0, you're probably wondering
whether an investment in NetWare API programming is going to burn
you.  The answer is, it depends.

Novell has done much to insure that NetWare 4.0 will remain backward
compatible with 3.x and 2.x.  However, it isn't clear yet how clean
this compatibility will be for programmers.

For example, to access a NetWare 4.x server from a DOS workstation,
you must use the NetWare Requester (VLM.EXE) which replaces the NetWare
shell (NETX and its counterparts).  Fortunately, you can use this same
requestor to access a NetWare 3.x or 2.x server (providing what is called
a "bindery connection").  VLM.EXE loads a number of modules depending on
how it is configured by the user or system adminstrator.  Much of the
backward compatibility is provided by a module called NETX.VLM.

So far, so good.  NETX.VLM will provide a "shell" interface for you,
so most (if not all) of the NETTO APIs should work.  However, if the user
or system administrator decides that they don't want to use NETX.VLM
(and they eventually will, because NETX.VLM exacts a performance and
memory penalty) then your NetWare APIs may not work, and you'll have
to recode or update to some new APIs.

Will NETTO be updated to reflect the new APIs?  I would certainly like
to do it, and certainly plan on learning what they are, but with a
public domain library, there's no guarantee.  So it's your decision.

!short: What about NetWare 4.0's Directory Services?
'---------------------------------------------------------------

Directory Services is Novell's replacement for Bindery Services.

This will be a problem, and not just for NETTO.  Clipper third party
library vendors, including NETTO, create high level libraries for you
by working at the assembly level.  Although NETTO is Clipper code,
we're really loading registers and calling interrupts so we're
working at the assembly level.

As of this writing, Novell was preparing to release the assembler APIs
to developers.  It may be nearly impossible for assembly programmers
to do Directory Services (DS) calls for a couple of reasons:

        - DS calls require RSA encryption algorithms that
          are licensed by Novell and aren't available at the
          assembler level

        - DS calls require text be passed back and forth in
          a format called Unicode which supports internationalization.
          While not a showstopper, it means assembler programmers
          must write unicode interfaces to the DS APIs.

So it is doubtful that you will see Directory Services APIs from _any_
Clipper third party vendor, but we could be wrong.

The only alternative is to program in C and use Novell's Client API
for C, or in a Windows-based language that can make calls to Novell's
Dynamic Link Libraries (DLLs).  If you plan to be working under
CA-Visual Objects for Clipper, then you will be able to make such calls
to the NetWare APIs directly, without NETTO or anyone else acting as
a middleman.

If you are doing bindery calls with NETTO or another CLipper third party
library then you will probably be okay if the 4.0 server you're working
with is doing bindery emulation.  If it isn't, then as one Novell
engineer told us, "You're toast."  You'll have to either drop the
bindery calls, or get the supervisor to run bindery emulation.

[And, it is possible that the creative Clipper third party market will
have solved this for you some other way by the time it matters. I
wouldn't put it past 'em.]

!short: What to do if you're clueless
'---------------------------------------------------------------

Okay, you've looked through this thing, and you're reading this
because you're pretty sure you still have no idea what it's all about.
Do not be ashamed.

When we were beta testing the NETTO library, we discovered that many
of the reported bugs were a result of inadequate understanding of
what's going on.  The obvious solution was to create better
documentation.

Did we?  Sometimes.  There were attempts at doing this, but it's
very difficult to muster up the energy to write a full how-to
article for a public domain project on which you've already spent too
much time.  Where the documentation is thin in NETTO, we apologize
and suggest that you:

     -  Ask

        If you're a CompuServe user, please send a message either
        to 71620,1521 or to All on the Clipper forum.  This will
        point out flaws in the documentation, which will force us
        to explain ourselves in print, which we will then
        capture with our comm software and put into the next release.
        You do your civic duty by asking.

     -  Read

        If you're technically inclined and think you've found a bug
        and feel comfortable rummaging around the NETTO source,
        please do so.  You might want to have available a NetWare
        API reference of some sort.  We might recommend Rose's book.
        Check the appropriate "Books and Publications" section of
        this on-line guide for more information.

      - Rewrite

        Why not figure out the problem (by asking/reading, etc) and
        then write up the explanation, improving on what is or isn't
        already there?  It would help others and it's a great way for
        you to contribute.

      - Buy a third party product

        NETTO was not intended to replace third party products.  Many
        of these companies, motivated by a desire to create
        added value and make some money, have written extensive
        documentation.  There's nothing stopping you from buying
        their products and using a combination of NETTO and the
        third party product if you want to.  You'll have a lot
        of functionality and you might get a very good manual.

In short, if you're clueless, don't worry about it.  Ask someone
who knows, get in touch with the authors, join the mailing list,
and experiment.

!short: Things to Do
'---------------------------------------------------------------

^bWould you like to help with:^b

More APIS!
NetWare 4.0 Compatibility (Requester support)
IPX/SPX
More documentation
Beginner's Guide
Clean up error codes
Use CA-Clipper error system