==============================================================

   Copyright 1994  Northeast Data Corp.  All Rights Reserved

==============================================================


==============================================================

  IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT


   Before experimenting with the Netcom control, read the
   information below. 

   The Netcom control allows you to perform network operations
   that disrupt network communication with your PC. Resetting
   the network adapter or deleting names from the NetBIOS
   name table indiscriminantly will destroy communication
   between your PC and other workstations on the network.

==============================================================
   

                     Netcom VBX V1.1d


The Netcom VBX control implements NetBIOS general, session, and
datagram support. All common NetBIOS functions are supported.

The control conforms to Visual Basic release 1.0, so it is
compatible with Visual Basic versions 1.0, 2.0, 3.0 and higher,
and with Visual C++ versions 1.0, 1.5 and higher.

This VBX control is also available from Northeast Data Corp.
as a standard Windows "Custom Control". This is a DLL that
can be used from C or C++ and is available from the Win 3.1
SDK Dialog Editor.

The only difference between the demo version of the control and
the commercial version is that the demo version displays a
dialog box that allows the user to register the control with
Northeast Data. There are no other functional differences.

Here are the overall capabilities:

   - Support for all standard NetBIOS emulations. This includes
     NetBIOS services running on LAN Manager, LAN Server, Novell,
     Banyan VINES, 3COM.

   - Support for multiple network adapters.

   - Multiple Netcom controls within the same application.

   - Interprocess communication between applications on the
     same workstation.

   - Communication between applications running on separate
     workstations.

   - Adapter status and reset.
   
   - NetBIOS name support.

   - NetBIOS session support.

   - NetBIOS datagram support.


===================
The demo version
===================

The demo version of the control will allow you to perform all functions
implemented by the commercial version. The only difference is that a
registration dialog box is displayed when the control is first loaded.

By registering the control with Northeast Data Corp., you get:

   - The commercial version of the control
   - A telephone and FAX number for support
   - A Compuserve ID for support
   - Free maintenance release updates
   - A discount on major releases
   - More information about using NetBIOS


===================
System Requirements
===================

You must have a NetBIOS application service running on your PC. This
requires a network adapter (etnernet, token ring, arcnet, etc.). This
service must be compatible with Microsoft Windows.

Microsoft Windows version 3.0 or 3.1.


===================
Installation
===================

Copy the NETCOM.VBX file to your Windows or Windows\System directory.

Before starting Windows, make sure you have loaded any network services
that are required for NetBIOS support.

Start Windows and run Visual Basic or the PROJECT1.EXE program supplied
with the Netcom control.

If you are running Visual Basic, you can load the PROJECT1.MAK file or
load the Netcom control into your own project by using the "Add File"
item under the FILE menu in Visual Basic.


===================
Control Properties
===================

Note: In the descriptions below, there are references to the "remote"
      workstation. If you are doing interprocess communication on your
      PC, "remote" refers to the other application on your PC. If you
      are communicating with a real remote workstation, "remote" refers
      to that workstation. 

      Since the Netcom control is re-entrant, you can actually perform
      inter-process communication within the control itself. In other
      words, you can send data to "yourself". It is perfectly OK to 
      have the Netcom control send data to and from itself or between
      Netcom controls in the same application. This has no value within
      the same application, other than allowing you to experiment with 
      the control.

Adapter

      The network adapter number. If you have only one network adapter,
      this number is always 0. You change this value to choose a different
      adapter.

Command

   All of the following commands are executed on the adapter specified in
   the "Adapter" property, which defaults to zero and is the correct value
   if you only have one network adapter.

   For all commands, you should set up an error handler (using the On Error
   VB statement). The error codes returned are documented in the NETCOM.H
   file (the errors with the "VBERR_" prefix.

   1 - Initialize

      Sets up the control for use by your application. This command
      must be executed before you perform any other commands and before
      any properties that perform network operations are executed.
   
   2 - RegisterName

      Registers the name specified in the "NetName" property with
      NetBIOS. The name is registered as a unique network name. The
      command fails if the name is already registered by anyone on
      the network.

   3 - RegisterGroup

      Registers the name specified in the "NetName" property with
      NetBIOS. The name is registered as a group name. The
      command fails if the name is already registered on your
      workstation, or if another workstation has registered the name
      as a unique name (see command #2). Group names can be used to
      send data to multiple workstations.

   4 - SendDatagram

      Sends the data specified in the "SendData" property to the
      name specified in the "RemoteName" property. The RemoteName
      property can be set to a unique name or a group name. The
      datagram is sent with the sender name specified in the "NetName"
      property. This name must be registered (using command 2 or 3)
      before sending the datagram. All workstations that have registered
      the remote name and have posted a "Receive Datagram" will receive
      the data you specify in the SendData property. Since this is a
      datagram, you receive no notification that other workstations
      have received the data.
                                                     
   5 - ReceiveDatagram

      Sets up a "receive datagram" for the name specified in the "NetName"
      property. You have to register NetName as a unique name or a
      group name before executing this command. After executing this
      command, control will be returned to your application. When a
      datagram is received, the Netcom "RecDatagram" procedure will
      be called (see below, under "Events"). 

   6 - Call

      An attempt is made to establish a session with the workstation
      that has registered the name specified in the "RemoteName" property.
      The name of the caller (you) is specified in the "NetName" property.
      You have to register the NetName before executing this command. You
      do not have to register the RemoteName. Both names can be either
      unique or group names. Control is returned immediately to your
      application. When a connection is established with a remote workstation,
      the "NewSendSession" routine is called in the Netcom control.

   7 - Listen

      A listen is set up for the name specified in the "RemoteName"
      property. The remote workstation expects you to supply a valid
      name in the "NetName" property. The NetName must be a unique or
      group name that you have registered using commands 2 or 3. This
      command returns immediately to your application. When a remote
      workstation calls you, the "NewRecSession" routine in the NetCom
      control is called. You can use this event to start sending or
      receiving data to or from the remote workstation.

   8 - Send

      Data you have specified in the "SendData" property is sent to the
      remote workstation. Control is immediately returned to your
      application. When the remote workstation has received the data,
      the "SendComplete" routine in the Netcom control is executed. You
      can use this notification to determine when to send the next block
      of data. The data is sent to the session specified in the "SendSession"
      property. 

   9 - Receive
      
      A wait for data is set up for the session specified in the "RecSession"
      property. Control is immediately returned to your application. When
      data is received, the "RecData" routine in the Netcom control is called.
      In order to receive more data from the sender, you must issue another
      "Receive" command. This should be done immediately to prevent the sender
      from timing out.

   10 - HangupReceive

      Terminates the session specified in the "RecSession" property. The
      remote workstation is notified. You can no longer receive data on this
      session.

   11 - HangupSend

      Terminates the session specified in the "SendSession" property. The
      receiving workstation, if any, is notified. You can no longer send
      data on this session.
      
   12 - CancelAll

      Cancels all network requests. This includes all commands for sending
      or receiving datagrams or data. It does not clear any registered
      names from the name table.

   13 - ResetAdapter

      Cancels all network requests and clears all names from the name table.
      USE THIS COMMAND WITH CAUTION. If you are running on a network, this
      command will delete all names that other workstations may be using to
      communicate with your workstation. The adapter will be set to the
      same state is was when your workstation was initially booted (before
      any network applications were started).

   14 - DeleteName

      Deletes the name specified in the "NetName" property from the NetBIOS
      name table. USE THIS COMMAND WITH CAUTION. Network servers and 
      applications register network names for communication with your
      workstation. If you delete names that have been registered by your
      network applications, these applications will no longer be able to
      perform network operations. This command deletes a group name or
      unique name, depending on the name specified in the NetName property.

   15 - ReceiveAny

      Sets up a receive for any remote workstation attempting to send data
      to the name you specify in the "NetName" property. This is different
      from the "Receive" command, which only accepts data from a workstation
      that has registered the name you specify in the "RemoteName" property.
      Control is returned immediately to your application. When a remote
      workstation sends data, the "RecData" routine in the Netcom control
      is called.

      If you specify 255 in the "NameNumber" property, instead of setting
      the "NetName" property, a "Receive-any-for-any" command is executed.
      This will set up a receive for any remote workstation sending data
      to any name (rather than a single name) on your workstation.

   16 - AdapterStatus

      Displays a dialog box containing information about the adapter you
      specify in the "RemoteName" property. If you specify "*" in this
      property, information from your own adapter will be displayed. If
      you specify a unique or group name, information from the first adapter
      that has registered the specified name will be displayed.

   17 - ListNames

      The "NetName" routine in the Netcom control is called for every
      name in the NetBIOS name table for the adapter specified in the
      "RemoteName" property. If the RemoteName property is "*", you 
      will get all the names registered on your workstation. If the
      remotename is set to a unique or group name, you will get the
      list of names registered by the first adapter on the network
      that has registered the specified name.

   18 - RecSessionStat

      Gets the session status for the session specified in the "RecSession"
      property. This command is not very useful, since the only status ever
      available is either 0 (failure) or 3 (session established). The other
      statuses only occur in rare situations. The "SessionStatus" property
      is set to the status of the receive session. Session status values are:

            1 - Listen pending
            2 - Call pending 
            3 - Session established
            4 - Hang Up pending
            5 - Hang Up complete   
            6 - Session aborted
   
   19 - SendSessionStat

      Gets the session status for the session specified in the "SendSession"
      property. This command is not very useful, since the only status ever
      available is either 0 (failure) or 3 (session established). The other
      statuses only occur in rare situations. The "SessionStatus" property
      is set to the status of the send session. Session status values are:

            1 - Listen pending
            2 - Call pending 
            3 - Session established
            4 - Hang Up pending
            5 - Hang Up complete   
            6 - Session aborted
 

   20 - ReceiveBroadcast

      Sets up a "Receive Datagram" for any workstation sending a broadcast
      datagram. Control returns immediately to your application. When a
      datagram is broadcasted by a remote workstation, the RecDatagram
      routine is called in the Netcom control. 

   21 - SendBroadcast
   
      Sends a datagram to all workstations on the network. You specify the
      data to send in the "SendData" property. All workstations that have
      posted a "Receive Broadcast Datagram" will receive the message. Since
      this is a datagram, your workstation will not be notified as to whether
      or not any workstations have received the message.


DragIcon    

      A standard Visual Basic property.

DragMode

      A standard Visual Basic property.

Index

      A standard Visual Basic property.

Left
      A standard Visual Basic property.

Name

      A standard Visual Basic property.

NameNumber

      The name number of the NetBIOS name specified in the "NetName"
      property. You can override this value for sending broadcast
      datagrams. This property is set automatically whenever you
      change the NetName property. 

NetName

      The NetBIOS name for performing various network requests. This
      can be a unique name or group name. You set this property and
      then issue a "registerName" or "registerGroup" command to put
      the name into the NetBIOS name table.

PermanentName

      Your adapter permanent node name. This is filled in automatically
      when you issue the "Initialize" command.

RecSession

      The number of the network session returned from a "NetListen"
      command.

RemoteName

      The NetBIOS remote name used for performing CALL, RECEIVE, and
      SEND commands.

SendData

      Data to be sent as a datagram or to be sent to a remote workstation
      using the "SendDatagram", "SendBroadcast", or "Send" commands.

SendSession

      The number of the network session returned from the "NetCall"
      command.

SessionStatus

      The status from the "SendSessionStat" or "RecSessionStat" commands.
      The values are:


            0 - Unknown

            1 - Listen Pending

            2 - Call Pending

            3 - Session Established

            4 - Hangup Pending
         
            5 - Hangup Complete

            6 - Session Aborted
 
TabIndex

      A standard Visual Basic property.

TabStop

      A standard Visual Basic property.

Tag

      A standard Visual Basic property.

Top

      A standard Visual Basic property.

Trace

      If set to TRUE, diagnostic messages are displayed for every
      network command performed. This is useful for troubleshooting
      your application.

Visible

      A standard Visual Basic property.



============
Events
============

RecDatagram (Datagram as String,Sender as String)

   Called when a datagram is received. "Datagram" is the string that
   was sent by the remote workstation. "Sender" is the name that the
   remote workstation used as the sender of the datagram.

NewSendSession (Receiver as String,I as Integer)

   Called when a new session has been established as a result of issuing
   the "Call" command. "Receiver" is the name that the responding workstation
   used to connect with your workstation. "I" is the session number.

NewRecSession (Sender as String,I as Integer)

   Called when a new session has been established as a result of issuing
   the "Listen" command. "Sender" is the name that the remote (sending)
   workstation used to connect with your workstation. "I" is the session 
   number.

NetName (S as String,I as Integer)

   Called repeatedly when a "ListNames" command is issued, for each name
   found in the NetBIOS name table. S is the registered name. I is the
   name number.

RecData (RecData as String,I as Integer)

   Called when data is received on a session. RecData is the data that
   was received. I is the session number, which matches the session
   number that was returned from the "Listen" command.


SessionClosed (I as Integer)

   Called when a session has been closed by the remote workstation.
   I is the number of the session. You can no longer issue sends or
   receives on this session.   

SendComplete (I as Integer)

   A remote workstation has successfully recieved the data you sent
   in a "Send" command. I is the session number.


=============================
General Notes
=============================

The demo application uses most of the NetBIOS functions implemented in
the Netcom control. The TRACE property is set to TRUE in the demo, so
you will see many messages as commands are executed. Since many operations
are asynchronous, you will see messages that appear to be out of order.
For example, you may see a message indicating that a datagram has been
received - followed by a message indicating that the datagram has been
sent. This is normal behavior.

With the TRACE function in operation, you will see messages indicating
that operations are successful - possibly followed by messages indicating
that an operation has failed. This is because many NetBIOS commands are
performed in two steps - the first step being the submission of a request
to the NetBIOS driver. The driver acknowledges that it has received the
request (hence the "success" message). After the operation has been 
completed, NetBIOS notifies the Netcom control as to the final status of
the operation. This status may be "success" or "failure" and is reported
back to the application (and directly to the screen if the TRACE function
is active).

Certain NetBIOS operations do not happen instantly. A request to add a
new name to the name table is time consuming (perhaps 5 seconds or more).
This request is handled synchronously by the Netcom control. It does not
return control to your application until the name has been added or the
attempt fails. 

The Netcom control has been designed with consideration efficient operation
of your workstation and ease of programming. There are "tradeoffs" between
asynchronous vs. synchronous operations. Synchronous operations are easier
for your application to deal with, but require suspending all execution
in your application until the operation completes. Asynchronous operations
allow your application to do other work while a request is being processed,
but are more difficult for your application to work with - you have to
handle the events that are sent to the Netcom control.

It is possible to do both sends and receives on the same session, even
though you initiated the session via a Call or Listen. Completion of a
"Call" fills in the "Sendsession" property. Completion of a "Listen" fills
in the "RecSession" property. If you perform a "Listen" and then want to
do a "Send", copy the "RecSession" value into the "SendSession" property
and then issue the "Send" command. Do the reverse for performing a "Receive"
on a session that was established by issuing a "Call" command.

=============================
Additional Information
=============================

Much of the information above assumes knowledge of NetBIOS. For more
information, consult:

   C Programmers Guide to NetBIOS, IPX, and SPX  by W. David Schwaderer,
   SAMS Publishing, a division of Prentice Hall Computer Publishing,
   11711 North College, Carmel, Indiana 46032, USA





   ================================================================

      Northeast Data Corp.
      2117 Buffalo Rd., Suite 290
      Rochester, NY  14624
      716-247-5934 (phone & FAX)

   ================================================================

   April 3, 1994

