
                      Assembly Login APIs Documentation
                          Keyed Login Object Modules


                             Last Update: 05/14/93


                                  Version 1.30


    This software is provided as is and carries no warranty
    whatsoever.  Novell disclaims and excludes any and all implied
    warranties of merchantability, title and fitness for a particular
    purpose.  Novell does not warrant that the software will satisfy
    your requirements or that the software is without defect or error
    or that operation of the software will be uninterrupted.  You are
    using the software at your risk.  The software is not a product
    of Novell, Inc. or any of its subsidiaries.


This document describes the functions contained in the various object files
included with ALOGIN.ZIP.  These functions allow you to perform a keyed login
to a NetWare 3.x file server as well as change or verify a bindery object's
password.  In addition, they support Novell's new NCP Packet Signature for
NetWare 3.11.  These OBJs can be linked with languages using the Microsoft
segment naming conventions.

Beginning with version 1.20, the Assembly Login support (ALOGIN) has been
built five different ways for each memory model.

           Full API support for DOS utilities
           Full API support for VAPs (No Packet Signature support)
           Login-ONLY support for DOS
           VerifyPassword-ONLY support for DOS
           ChangePassword-ONLY support for DOS

For those needing the support of only a single API, the new "?-ONLY" build
results in quite a substantial memory savings.  The filename convention table
below describes how the APIs are organized in the object modules.

One very important note here is that the new AsmLoginToFileServer() API no
longer supports the old-style login request (E3h-14h).  Thus, this API cannot
login to any NetWare installation which does not support keyed logins.  i.e.
pre-2.15c NetWare.


Object Naming Convention:

    mLOGIN.OBJ - Contains all three APIs
        m is one of S,M,C or L for Small, Medium, Compact and Large


The VAP objects have a 'v' appended to the root name.  i.e.

    sLOGINv.OBJ - Small Model VAP object

The current release of the VAP objects does NOT support NCP Packet Signature.


The ONLY objects are named as follows:

    mLOGINX.OBJ - Contains AsmLoginToFileServer ONLY
    mVERIFY.OBJ - Contains AsmVerifyBinderyObjectPassword ONLY
    mCHANGE.OBJ - Contains AsmChangeBinderyObjectPassword ONLY
        m is one of S,M,C or L for Small, Medium, Compact and Large



IMPORTANT NOTES:

These functions all assume that you are attached, and the preferred
connection is set to the server that you want to login to or change the
password on.  You must perform those APIs before calling the functions in
this object, or they will not work.  If you need more information on this
requirement, please call Novell Developer Support.

All Functions require approximately 254 bytes of stack space for local
variables.  This does not include the overhead for calling DOS or the
shell via Int 21h.  You must provide sufficient stack space for this.
VAP users need to allow for overhead of the NetWareShellServices API.

Objects are provided for the SMALL, MEDIUM, COMPACT and LARGE memory
models.  There are three functions included in each object module:

    _AsmLoginToFileServer           (ObjName, ObjType, ObjPassword)
    _AsmVerifyBinderyObjectPassword (ObjName, ObjType, ObjPassword)
    _AsmChangeBinderyObjectPassword (ObjName, ObjType, ObjOldPass, ObjNewPass)

Where:
        ObjName     - A pointer to the Object's Name
        ObjType     - The Object's Type i.e. 1 for USER, ...
        ObjPassword - A pointer to the Object's Password.
        ObjOldPass  - A pointer to the Object's old Password.
        ObjNewPass  - A pointer to the Object's new Password.

NOTE:
    All pointers are model dependant. i.e. 2 byte for small and medium model
    or 4 byte for compact and large.

    Also, a global variable called __AsmDataElement has been declared.
    __AsmDataElement is used to establish DS addressability BEFORE
    calling any of the other APIs.  This is ONLY needed if DS is NOT
    pointing to DGROUP.  If you will be calling the APIs without DS
    pointing to DGROUP, you need to establish addressability first.
    To do this, just "MOV AX,SEG __AsmDataElement", and "MOV DS,AX"
    before calling the API.  Be sure to save DS for your program!

All functions return a status code in the AX register.  See your System Calls
Documentation for a description of the return codes.

Only registers SI, DI, BP, DS and ES are preserved.  All others are destroyed.

To call any of these functions, simply push the parameters onto the stack in
the reverse order i.e. right to left.  Be sure to pass the correct pointer
size!  Following are samples for calling a small and large model function.

                ;Small Model Example
                mov     ax,offset DGROUP:Password   ; user password
                push    ax
                mov     ax,1                        ; type user
                push    ax
                mov     ax,offset DGROUP:Username   ; user name
                push    ax
                call    near ptr _AsmLoginToFileServer

                ;Large Model Example
                push    ds
                mov     ax,offset DGROUP:Password   ; user password
                push    ax
                mov     ax,1                        ; type user
                push    ax
                push    ds
                mov     ax,offset DGROUP:Username   ; user name
                push    ax
                call    far ptr _AsmLoginToFileServer


*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
                        Special Info for VAP users
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

This section applies only to users of the VAP routines.

You must provide a routine in your prelude module called:

    '_CallNetWareShellServices'

which will perform a call to the NetWareShellServices entry point as
specified in the VAPs Header.  Following is a sample of what it must look
like:

_CallNetWareShellServices  proc             ; for login.obj
                public  _CallNetWareShellServices
                push    ds                  ; save ds
                xchg    si,bx               ; on entry si:bx pointer to
                mov     ds,bx               ;  request, make ds:si instead
                call    dword ptr cs:[NetWareShellServices]   ; call OS
                pop     ds                  ; restore ds
                cbw                         ; return code in AX
                ret
_CallNetWareShellServices  endp             ; for login.obj
