          INVISIBLE LAN NETBIOS APPLICATION PROGRAM INTERFACE

              Copyright 1986-1992 Invisible Software, Inc.




     Invisible LAN includes a software interface compatible with the IBM
NetBIOS.  This allows Invisible LAN to run software designed for the IBM
PC Network, IBM Token-Ring Network, and other NetBIOS-compatible
networks.  The design of NetBIOS is based on the following principles:

     1.  Peer Network - Each station on the network is treated equally,
and has equal access to the network.  It is not required that there be
any centralized host or server.

     2.  High-Level Software Interface - The NetBIOS provides
application programs with high-level services, including name support,
session support, and datagram support.  As a result, applications
programs do not concern themselves with the details of low-level network
protocols.  This greatly simplifies the writing of applications
programs.

     3.  Hardware Independence - The services provided by NetBIOS are
largely independent of the hardware used to implement the network.  As a
result, an application program designed to run on one set of hardware
can also run on a completely different set of hardware, so long as both
sets of hardware provide NetBIOS interfaces.

     4.  Name Support - Stations on the network are referred to by
logical names selected by the user, such as "John" or "Mary", instead of
station numbers like "154".  It is possible for one station to have more
than one name.  It is also possible to define a group name which can be
used by more than one station;  for example, the name "Accounting" could
be used by everyone in the accounting department.

     5.  Session Support - Once two stations have names assigned to
them, they can communicate by establishing a session (also called a
virtual circuit).  The session allows the two stations to send data to
each other.  NetBIOS automatically checks to ensure that all data sent
by one of the stations is reliably received by the other station.

     6.  Datagram Support - Datagrams are short messages that are
typically used for broadcasting a message to many stations
simultaneously.  NetBIOS does not guarantee that datagrams will be
received, so any desired acknowledgements and retransmissions must be
done by the user.

     7.  Station Independence - Thanks to the use of logical names,
users do not have to know the physical locations of shared resources,
and programs that manage shared resources do not have to know the
physical locations of users.  Users and shared resources are simply
referred to by their logical names, and NetBIOS automatically routes
data to the correct physical location.  This gives both users and
resources the freedom to move from station to station within the network
without having to modify existing programs or procedures.




------------------------------------------------------------------------




TABLE OF CONTENTS


1.  Summary of Compatibility Issues
2.  How to Issue a Command to NetBIOS
3.  Network Control Block (NCB) Description
   3.1.  NCB_COMMAND
      3.1.1.  Wait Commands
      3.1.2.  No-Wait Commands
   3.2.  NCB_RETCODE
   3.3.  NCB_LSN
   3.4.  NCB_NUM
   3.5.  NCB_BUFFER
   3.6.  NCB_LENGTH
   3.7.  NCB_CALLNAME
   3.8.  NCB_NAME
   3.9.  NCB_RTO
   3.10.  NCB_STO
   3.11.  NCB_POST
   3.12.  NCB_LANA_NUM
   3.13.  NCB_CMD_CPLT
   3.14.  NCB_RESERVE
4.  General Commands
   4.1.  RESET
   4.2.  CANCEL
   4.3.  ADAPTER STATUS
   4.4.  UNLINK
   4.5.  IDENTIFY
   4.6.  PRESENCE TEST
5.  Name Support Commands
   5.1.  ADD NAME
   5.2.  ADD GROUP NAME
   5.3.  DELETE NAME
   5.4.  FIND NAME
6.  Session Support Commands
   6.1.  CALL
   6.2.  LISTEN
   6.3.  HANG UP
   6.4.  SEND
   6.5.  CHAIN SEND
   6.6.  INCOMPLETE SEND
   6.7.  RECEIVE
   6.8.  CHAIN RECEIVE
   6.9.  RECEIVE ANY
   6.10.  SESSION STATUS
7.  Datagram Support Commands
   7.1.  SEND DATAGRAM
   7.2.  SEND BROADCAST DATAGRAM
   7.3.  RECEIVE DATAGRAM
   7.4.  RECEIVE BROADCAST DATAGRAM
8.  Error Codes
9.  The Remote Program Load (RPL) Facility
   9.1.  Remote Program Load Procedure
   9.2.  The Disk Redirector
      9.2.1.  Read Sector Commands
      9.2.2.  Write Sector Commands
      9.2.3.  Other Disk Commands
10.  NetBIOS Programming Hints
   10.1.  Sessions Versus Datagrams
   10.2.  WAIT-POST Inversion
   10.3.  RECEIVE Ordering and Posting
   10.4.  Using CANCEL
   10.5.  The Meaning of Local Session Numbers
   10.6.  The Meaning of Name Numbers
   10.7.  When an NCB Can Be Re-used
   10.8.  Issuing INT 5CH Within NCB_POST
   10.9.  Programming a Server-Client Connection
      10.9.1.  Opening Connections
      10.9.2.  Transactions - Client End
      10.9.3.  Transactions - Server End
         10.9.3.1.  RECEIVE ANY Method
         10.9.3.2.  RECEIVE-Per-Session Method
         10.9.3.3.  Multiple RECEIVE ANY Method
      10.9.4.  Closing Connections
      10.9.5.  Error Handling - Client End
      10.9.6.  Error Handling - Server End




------------------------------------------------------------------------




1.  SUMMARY OF COMPATIBILITY ISSUES


     The following is a summary of known differences between the
Invisible LAN NetBIOS, the IBM PC Network NetBIOS, and the IBM Token
Ring NetBIOS.

     1.  The maximum possible number of outstanding commands is 254 for
Invisible LAN, 32 for IBM PC Network, and 255 for IBM Token Ring
Network.

     2.  The maximum possible number of sessions is 254 for Invisible
LAN, 32 for IBM PC Network, and 254 for IBM Token Ring Network.

     3.  The maximum possible number of names is 253 for Invisible LAN,
16 for IBM PC Network, and 254 for IBM Token Ring Network.

     4.  In the RESET command, Invisible LAN ignores the values of
NCB_LSN and NCB_NUM.  The IBM PC Network and IBM Token Ring Network use
these values to specify the number of sessions and commands to be
supported.  Refer to the description of the RESET command for details.

     5.  In the CALL and LISTEN commands, Invisible LAN ignores the
values of NCB_RTO and NCB_STO.  The IBM PC Network and IBM Token Ring
Network uses these values to specify timeouts for receiving and sending
data.  Refer to the description of the CALL and LISTEN commands for
details.

     6.  The Invisible LAN cannot cancel the following commands:
ADAPTER STATUS, CALL, and HANG UP.

     7.  Invisible LAN and IBM Token Ring Network support the FIND NAME
command.  The IBM PC Network does not support FIND NAME.

     8.  The IBM Token Ring Network supports the TRACE command.
Invisible LAN and the IBM PC Network do not support TRACE.

     9.  Invisible LAN supports the following commands:  IDENTIFY,
INCOMPLETE SEND, and CHAIN RECEIVE.  The IBM PC Network and IBM Token
Ring Network do not support these commands.

     10.  In the data returned by ADAPTER STATUS, some of the fields
have different meanings in different networks.  Refer to the description
of the ADAPTER STATUS command for details.

     11.  When a HANG UP is issued on a session that has outstanding
SEND commands, the behavior of the Invisible LAN is sometimes different
than the behavior of the IBM PC Network.  Refer to the description of
the HANG UP command for details.

     12.  Invisible LAN allows the use of NCB_NUM = 0FFH in the RECEIVE
BROADCAST DATAGRAM command.  The IBM PC Network and IBM Token Ring
Network do not allow this.

     13.  On Invisible LAN and IBM Token Ring Network, an NCB_POST
routine does not have to preserve any CPU registers.  On the IBM PC
Network, an NCB_POST routine must preserve the BP register.

     14.  For the ADAPTER STATUS and SESSION STATUS commands, if the
buffer is too small to hold the data, the Invisible LAN behaves
differently than the IBM PC Network.  Refer to the command descriptions
for details.




------------------------------------------------------------------------




2.  HOW TO ISSUE A COMMAND TO NETBIOS


     All commands are issued to NetBIOS in the form of a Network Control
Block (NCB).  The NCB is a standard 64-byte data structure used for
communicating between the NetBIOS and the application program.  Before
calling NetBIOS, the application fills in the NCB with all the
information that the NetBIOS needs to have in order to execute the
command.  When the NetBIOS completes the command, it makes the results
available to the application by storing the results into the NCB.

     The procedure for issuing a command to NetBIOS is:

     1.  Fill in all required fields in the NCB.  It is recommended,
though not required, that any unused fields be filled in with binary
zeros.

     2.  Allocate any data buffers required by the command.

     3.  Make sure there is at least 32 bytes of stack space for each
outstanding NCB command.

     4.  Place the address of the NCB into the ES:BX registers.

     5.  Issue an INT 5CH instruction.

     6.  Once the NCB is issued, you may not modify or move the NCB
until the command has completed.

     7.  When the command is complete, the NetBIOS will make a return
code available to the application in the AL register and the return code
field of the NCB.  Some other fields of the NCB may also contain
information returned by NetBIOS.




------------------------------------------------------------------------




3.  NETWORK CONTROL BLOCK (NCB) DESCRIPTION


     The network control block (NCB) is a 64-byte data structure used to
pass commands from the application to NetBIOS and return results from
NetBIOS to the application.  The NCB takes the following form:


NCB_COMMAND     DB      ?       ;Command code

NCB_RETCODE     DB      ?       ;Return code

NCB_LSN         DB      ?       ;Local session number

NCB_NUM         DB      ?       ;Name number

NCB_BUFFER      DD      ?       ;Pointer to data buffer (segment:offset)

NCB_LENGTH      DW      ?       ;Length of data buffer

NCB_CALLNAME    DB      16 DUP(?) ;Name on remote adapter.
                                ;For CHAIN SEND or CHAIN RECEIVE, the
                                ;first two bytes contain the length of
                                ;the second buffer, and the next 4 bytes
                                ;contain a pointer to the second buffer.

NCB_NAME        DB      16 DUP(?) ;Name on local adapter

NCB_RTO         DB      ?       ;Timeout value for receive commands.

NCB_STO         DB      ?       ;Timeout value for send commands.

NCB_POST        DD      ?       ;Pointer to post routine
                                ;(segment:offset)

NCB_LANA_NUM    DB      ?       ;Number of the adapter to use.  For the
                                ;Invisible LAN, must be 00H.

NCB_CMD_CPLT    DB      ?       ;If command has not completed, contains
                                ;0FFH.

NCB_RESERVE     DB      14 DUP(?) ;Reserved




3.1.  NCB_COMMAND


     The application program uses this field to specify the command that
is to be executed.  Bits 6-0 identify the command.  Bit 7, if set,
indicates that the no-wait form of the command is to be used.
(Exception:  For the PRESENCE TEST command, Bit 7 is ignored;  this
command is always executed in the wait form.) Any command except RESET,
CANCEL, UNLINK, and PRESENCE TEST can be given in the no-wait form.

     The interface between the application and NetBIOS is different
depending on whether you use the wait or no-wait form of a command.  The
following sections describe the two interfaces.




3.1.1  WAIT COMMANDS


     When you use the wait form of a command, the call to INT 5CH does
not return until the command has completed.  In this case, the final
return code is in both the AL register and the NCB_RETCODE field.

     When a command is given in the wait form, the NetBIOS issues WAIT
and POST function calls to INT 15H.  When the NetBIOS has started the
command, and is about to go into a loop waiting for the command to
complete, it issues a WAIT function call by calling INT 15H with
AX=9080H and ES:BX=the address of the NCB.  When the NetBIOS completes
the command, and is ready to return from the INT 5CH call, it issues a
POST function call by calling INT 15H with AX=9180H and ES:BX=the
address of the NCB.

     The WAIT and POST function calls make it possible for a
multitasking system to dispatch another task while the command is
executing.  The WAIT function call tells the multitasking system that
the task should be marked "suspended" and another task should be
dispatched.  The POST function call tells the multitasking system that
the task should be marked "ready to run".

     Remark:  It is possible for the POST function call to occur before
the corresponding WAIT function call.




3.1.2.  NO-WAIT COMMANDS


     When you use the no-wait form of a command, you get two return
codes:  an immediate return code and a final return code.  For no-wait
commands, the INT 5CH instruction does not wait for the command to
complete before returning.  The call to INT 5CH will return as soon as
the NetBIOS has started the command.  This allows the application
program to execute concurrently with the NetBIOS.

     On return from the call to INT 5CH, the AL register contains the
immediate return code.  The immediate return code indicates whether or
not the NetBIOS was able to start the command.  The possible immediate
return codes are:

     00H - Good return
     03H - Invalid command
     21H - Interface busy
     22H - Too many commands outstanding
     23H - Invalid NCB_LANA_NUM field
     40H-0FEH - Network malfunction

     If the immediate return code is 00H, the NetBIOS was able to start
the command.  In this case, the NetBIOS will make the final return code
available to the application when the command has completed.  There are
two ways that the application can obtain the final return code:

     1.  If the NCB_POST field is non-zero, the NetBIOS will call the
routine pointed to by NCB_POST when the command is complete.  The
routine can obtain the final return code from either the AL register or
the NCB_RETCODE field.

     2.  The application can examine the NCB_CMD_CPLT field.  If
NCB_CMD_CPLT contains 0FFH, then the command is not complete.  If
NCB_CMD_CPLT contains any other value, then the command is complete;  in
this case, NCB_CMD_CPLT contains the final return code.

     If the immediate return code is not 00H, the NetBIOS was not able
to start the command.  In this case, the NetBIOS does not call the
routine pointed to by NCB_POST.

     Remark:  It is possible for a no-wait command to complete before
the original call to INT 5CH returns.  Therefore, it is possible for the
NCB_POST routine to be called before the original INT 5CH return.




3.2.  NCB_RETCODE


     NetBIOS uses this field to return the final return code to the
application.

     A final return code of 00H indicates that the command was completed
successfully.  Any other return code indicates that an error occurred.
If the command has not yet completed, the return code is 0FFH.

     Remark:  Never examine NCB_RETCODE for the purpose of determining
whether or not the command has completed.  Use NCB_CMD_CPLT for this
purpose.




3.3.  NCB_LSN


     For the HANG UP, SEND, CHAIN SEND, INCOMPLETE SEND, RECEIVE, and
CHAIN RECEIVE commands, the application uses this field to specify the
local session number.

     For the RESET command, the application uses this field to specify
the number of sessions to be supported.  (However, Invisible LAN ignores
this value.)

     For the CALL, LISTEN, and RECEIVE ANY commands, NetBIOS uses this
field to return the local session number to the application.

     Note:  Each pending session has a local session number (LSN)
associated with it.  Local session numbers are assigned in a round-robin
"Modulo 254" technique ranging from 1 to 254.  00H and 0FFH are never
used as local session numbers.




3.4.  NCB_NUM


     For the RECEIVE ANY, SEND DATAGRAM, SEND BROADCAST DATAGRAM,
RECEIVE DATAGRAM, and RECEIVE BROADCAST DATAGRAM commands, the
application uses this field to specify the name number.  For RECEIVE
ANY, RECEIVE DATAGRAM, and RECEIVE BROADCAST DATAGRAM, a value of 0FFH
can be used as a wildcard to receive a message for any name.

     For the RESET command, the application uses this field to specify
the number of command blocks to be supported.  (However, Invisible LAN
ignores this value.)

     For the ADD NAME, ADD GROUP NAME, RECEIVE ANY, and RECEIVE DATAGRAM
commands, NetBIOS uses this field to return the name number to the
application.

     Note:  Each name in the local name table has a name number
associated with it.  Name numbers are assigned in a round-robin "Modulo
253" technique ranging from 2 to 254.  Name number 1 always refers to
the permanent node name.  00H and 0FFH are never used as name numbers.




3.5.  NCB_BUFFER


     For the ADAPTER STATUS, SEND, CHAIN SEND, INCOMPLETE SEND, RECEIVE,
CHAIN RECEIVE, RECEIVE ANY, SESSION STATUS, SEND DATAGRAM, SEND
BROADCAST DATAGRAM, RECEIVE DATAGRAM, RECEIVE BROADCAST DATAGRAM, FIND
NAME, and IDENTIFY commands, the application uses this field to specify
the buffer address.  The buffer address is given in segment:offset form.

     For the CANCEL command, the application uses this field to specify
the address of the NCB that is to be canceled.  The address is given in
segment:offset form.




3.6.  NCB_LENGTH


     For the ADAPTER STATUS, SEND, CHAIN SEND, INCOMPLETE SEND, RECEIVE,
CHAIN RECEIVE, RECEIVE ANY, SESSION STATUS, SEND DATAGRAM, SEND
BROADCAST DATAGRAM, RECEIVE DATAGRAM, RECEIVE BROADCAST DATAGRAM, FIND
NAME, and IDENTIFY commands, the application uses this field to specify
the length of the buffer.

     For the ADAPTER STATUS, RECEIVE, RECEIVE ANY, SESSION STATUS,
RECEIVE DATAGRAM, RECEIVE BROADCAST DATAGRAM, FIND NAME, and IDENTIFY
commands, NetBIOS uses this field to return the number of bytes actually
received.  For the CHAIN RECEIVE command, NetBIOS uses this field to
return the number of bytes that were placed into the first buffer.




3.7.  NCB_CALLNAME


     For the ADAPTER STATUS, CALL, LISTEN, SEND DATAGRAM, and FIND NAME
commands, the application uses this field to specify the name of the
station with which it wants to communicate.  All 16 characters are
significant, and lower-case letters are different than upper-case.  For
ADAPTER STATUS, a value of '*' in the first byte can be used to request
the status of the local station.  For LISTEN, a value of '*' in the
first byte can be used to listen for a call from any other station.  For
CALL, SEND DATAGRAM, and FIND NAME, no wildcarding is possible.

     For the CHAIN SEND and CHAIN RECEIVE commands, the first 6 bytes of
this field are used by the application to specify the second buffer.
The first 2 bytes are the length of the second buffer, and the next 4
bytes are the address of the second buffer in segment:offset form.

     For the LISTEN command, NetBIOS uses this field to return the name
of the station with which a session has been established.

     For the RECEIVE DATAGRAM and RECEIVE BROADCAST DATAGRAM commands,
NetBIOS uses this field to return the name of the station that sent the
datagram.

     For the CHAIN RECEIVE command, NetBIOS uses the first two bytes of
this field to return the number of bytes that were placed into the
second buffer.




3.8.  NCB_NAME


     For the ADD NAME, ADD GROUP NAME, and DELETE NAME commands, the
application uses this field to specify the name to be added or deleted.
All 16 characters are significant, and lower-case letters are different
than upper-case.  No wildcarding is possible.

     For the CALL and LISTEN commands, the application uses this field
to specify the local name to be used.  All 16 characters are
significant, and lower-case letters are different than upper-case.  No
wildcarding is possible.

     For the SESSION STATUS command, the application uses this field to
specify the local name for which status is being requested.  All 16
characters are significant, and lower-case letters are different than
upper-case.  A value of '*' in the first byte can be used to request the
status for all local names.




3.9.  NCB_RTO


     For the CALL and LISTEN commands, the application uses this field
to specify the timeout to be used with all RECEIVE and CHAIN RECEIVE
commands associated with the session, in units of 1/2 second.  A value
of 00H indicates that there is no timeout.  (However, Invisible LAN
ignores this value.)




3.10.  NCB_STO


     For the CALL and LISTEN commands, the application uses this field
to specify the timeout to be used with all SEND, CHAIN SEND, and
INCOMPLETE SEND commands associated with the session, in units of 1/2
second.  A value of 00H indicates that there is no timeout.  (However,
Invisible LAN ignores this value.)




3.11.  NCB_POST


     For no-wait commands, the application uses this field to specify
the address of a routine that is to be called when the command is
completed.  The address is in segment:offset form.  The routine is
called with interrupts disabled, ES:BX containing the address of the
NCB, and AL containing the final return code.  The routine should return
using IRET.

     The post routine should be short and return immediately, unless it
enables interrupts.  The post routine does not have to preserve CPU
registers, though it is considered good programming practice for the
post routine to preserve all registers except AX.  (Compatibility note:
In order to be compatible with the IBM PC Network Adapter, the post
routine must preserve the BP register.) It is legal for the post routine
to issue calls to INT 5CH, though this should be avoided if possible.

     If NCB_POST contains zero, then there is no call.

     For wait commands, this field is not used.  Instead, NetBIOS issues
WAIT and POST function calls via INT 15H.




3.12.  NCB_LANA_NUM


     For all commands except UNLINK, the application uses this field to
specify which network card is to be used.  For the Invisible LAN, this
field must contain 00H.

     Compatibility note:  The IBM PC Network and IBM Token Ring Network
allow two adapters to be installed in one computer at the same time.
For these networks, NCB_LANA_NUM selects one of the two adapters:  a
value of 00H selects the first adapter, and a value of 01H selects the
second adapter.




3.13.  NCB_CMD_CPLT


     For all commands, NetBIOS uses this field to indicate whether or
not the command has completed.  If the command is not complete, this
field contains 0FFH.  If the command is complete, this field contains
the final return code.




3.14.  NCB_RESERVE


     This field is reserved for use by NetBIOS.  The Invisible LAN's
NetBIOS does not use this field.

     Compatibility note:  The IBM PC Network and IBM Token Ring Network
use this field as a scratch work area.  Therefore, application programs
should always allocate the NCB_RESERVE field.




------------------------------------------------------------------------




4.  GENERAL COMMANDS


     General commands are used to examine or modify the status of the
NetBIOS.  The commands that fall into this category are:

     1.  RESET - Reset the local station, clearing all outstanding
names, sessions, and commands.

     2.  CANCEL - Abort a previously issued command.

     3.  ADAPTER STATUS - Obtain the status of the local station or a
remote station.

     4.  UNLINK - End the disk redirector used by the Remote Program
Load feature.

     5.  IDENTIFY - Identify all stations on the network.

     6.  PRESENCE TEST - Determine if there is a network adapter in the
computer.




4.1.  RESET


     Reset the local adapter, clear the session and name tables, and
abort all pending commands.

     Note 1:  This command does not clear the traffic and error
statistics.

     Note 2:  The RESET command can be issued only in the wait form.

     Note 3:  NetBIOS does not issue POST or NCB_POST function calls for
any commands that are aborted as a result of RESET.

     Compatibility notes:  On the IBM PC Network, NCB_LSN and NCB_NUM
specify the maximum number of sessions and command blocks to be
supported.  The number of sessions can range from 1 to 32, with a
default of 6.  The number of commands can range from 1 to 32, with a
default of 12.  If the specified values are too large, the maximum
allowed values are used;  if zeros are specified, the default values are
used.

     On the IBM Token Ring Network, the number of sessions and command
blocks can be specified in either the RESET command or the
DIR.OPEN.ADAPTER command.  If they are specifed in the DIR.OPEN.ADAPTER
command, then the NCB_LSN and NCB_NUM fields of the RESET command are
ignored.  In any case, the number of sessions can range from 1 to 254,
with a default of 6.  The number of commands can range from 1 to 255,
with a default of 12.  If zeros are specified, the default values are
used.

     The Invisible LAN NetBIOS is always configured for the number of
sessions and commands specified in the NET30.INI file, regardless of the
values specified in NCB_LSN and NCB_NUM.  (For ROM-based versions of
Invisible LAN NetBIOS, the number of sessions is always configured as
32, and the number of commands is always configured as 32.)


Fields Required:

NCB_COMMAND = 32H (Wait form).

NCB_LSN = Number of sessions to be supported.  Invisible LAN ignores
          this parameter.

NCB_NUM = Number of commands to be supported.  Invisible LAN ignores
          this parameter.

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




4.2.  CANCEL


     Abort the command whose NCB address is specified in NCB_BUFFER.

     Note 1:  The following commands cannot be canceled:  RESET, CANCEL,
UNLINK, IDENTIFY, ADD NAME, ADD GROUP NAME, DELETE NAME, FIND NAME,
SESSION STATUS, SEND DATAGRAM, and SEND BROADCAST DATAGRAM.  If you try
to cancel one of these commands, the CANCEL command will be returned
with error code 26H ("command not valid to cancel").

     Note 2:  Cancelling a SEND, CHAIN SEND, or INCOMPLETE SEND will
cause the session to be aborted.

     Note 3:  The CANCEL command can be issued only in the wait form.

     Compatibility note:  For the Invisible LAN, the following commands
cannot be canceled:  ADAPTER STATUS, CALL, and HANG UP.  If you try to
cancel one of these commands, the CANCEL command will be returned with
error code 24H ("command completed while cancel occurring").


Fields Required:

NCB_COMMAND = 35H (Wait form).

NCB_BUFFER = Address of the NCB to be canceled.

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

23H = Invalid NCB_LANA_NUM.

24H = Command to be canceled was already completed or never existed.

26H = Command not valid to cancel.

40H-0FEH = Network malfunction.




4.3.  ADAPTER STATUS


     Receive the status of the adapter specified in NCB_CALLNAME.  By
specifying the appropriate name in NCB_CALLNAME, you can obtain the
status of either the local station or a remote station.  If the first
byte of NCB_CALLNAME contains an "*", then the status of the local
station is returned.

     The status information is placed into the buffer specified by
NCB_BUFFER, and the length of the status information is returned in
NCB_LENGTH.

     The buffer length required to receive all the status information is
60 bytes plus 18 bytes for each entry in the name table.  If the buffer
length is too small, error code 06H ("message incomplete") is returned,
as much data as possible is placed in the buffer, and the remaining data
is lost.

     Compatibility note:  The IBM PC Network Technical Reference Manual
states that if the buffer is too small then error code 06H ("message
incomplete") should be returned, as described above.  However, in this
circumstance the IBM PC Network Adapter will actually return error code
01H ("illegal buffer length"), and no status information at all is
placed into the buffer.


Fields Required:

NCB_COMMAND = 33H (Wait form) or 0B3H (No-wait form).

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_CALLNAME = Name of station for which status is desired, or "*" for
               local adapter status.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Length of status data returned.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length.

03H = Invalid command.

05H = Specified name cannot be found on the network.

06H = Message incomplete.

0BH = Command canceled.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.



Data returned:


Hardware configuration - 10 bytes:

(6 bytes) Unit identification number:

          Each station on the network has a unique unit identification
          number.  The number is stored least significant byte first.

          Note 1:  The unit identification number forms part of the
          permanent node name.  The 16-byte permanent node name consists
          of 10 bytes of binary zeros followed by the 6-byte unit
          identification number.

          Note 2:  For Invisible LAN the unit identification number may
          be interpreted as follows, where the six bytes are considered
          to be numbered from 0 to 5:

          (a) If byte 5 equals 49H, and byte 1 equals 0FFH, then the
              hardware is the old Model 300 series.  In this case, byte
              0 contains the hardware address times two.

          (b) If byte 5 equals 49H, and byte 1 does not equal 0FFH, then
              the hardware is the old Invisible Ethernet series E or N.
              In this case, bytes 0 and 1 contain the hardware address
              times two (byte 0 is the low-order byte, and byte 1 is the
              high-order byte).

          (c) If byte 5 does not equal 49H, then bytes 0, 1, and 4
              contain the serial number (byte 0 is the low-order byte,
              and byte 4 is the high-order byte).

          Compatibility notes:  For the IBM PC Network, the unit
          identification number is stored least significant byte first.
          For the IBM Token Ring Network, the unit identification number
          is stored most significant byte first.

(1 byte) Status byte #1:

         For the Model 300 series, this contains the following bits:

           Bits 7-6 = Speed setting:
                      00 = 1.8 Mbps
                      01 = 3.0 Mbps
                      10 = 1.4 Mbps
                      11 = 0.7 Mbps
           Bit 5 = DMA channel (ISA), Arbitration level (Micro Channel):
                   0 = DMA channel 1, or Arbitration level 0
                   1 = DMA channel 5, or Arbitration level 1
           Bits 4-3 = Product code:
                      00 = Model 100, 200, or 200/A
                      01 = Model 300 or 300/A
                      10 = Invalid
                      11 = Invalid
           Bit 2 = Setting of option jumper #2 (Model 300 only)
           Bit 1 = Setting of option jumper #1 (Model 300 only)
           Bit 0 = Master station setting (Models 300, 300/A only):
                   0 = Master
                   1 = Non-master

         For Invisible Ethernet-8:

           Bits 7-6 = Not used
           Bits 5-4 = I/O port:
                      00 = 300H
                      01 = 320H
                      10 = 340H
                      11 = 360H
           Bits 3-2 = DMA channel (1 or 3), or 0 if DMA is not used
           Bits 1-0 = Interrupt level:
                      00 = IRQ 2
                      01 = IRQ 3
                      10 = IRQ 4
                      11 = IRQ 5

         For Invisible Ethernet-16, Ethernet-1000, Ethernet-2000, and
         all NE-1000 and NE-2000 compatibles:

           Bits 7-4 = I/O port:
                      0000 = 300H
                      0001 = 320H
                      0010 = 340H
                      0011 = 360H
                      0100 = 380H
                      0101 = 3A0H
                      0110 = 3C0H
                      0111 = 3E0H
                      1000 = 200H
                      1001 = 220H
                      1010 = 240H
                      1011 = 260H
                      1100 = 280H
                      1101 = 2A0H
                      1110 = 2C0H
                      1111 = 2E0H
           Bits 3-0 = Interrupt level

         For Invisible Ethernet/A:

           Bits 7-4 = I/O port:
                      0000 = 5400H
                      0010 = 5440H
                      1000 = 5500H
                      1010 = 5540H
           Bits 3-0 = Interrupt level

         For Invisible Ethernet-2/A and all NE/2 compatibles:

           Bits 7-5 = I/O port:
                      000 = Invalid
                      001 = 1000H
                      010 = 2020H
                      011 = 8020H
                      100 = 0A0A0H
                      101 = 0B0B0H
                      110 = 0C0C0H
                      111 = 0C3D0H
           Bit 4 = Not used
           Bits 3-0 = Interrupt level

         For Invisible or Accton Parallel Port Ethernet:

           Bit 7 = Printer port mode:
                   0 = bidirectional (fast) mode
                   1 = unidirectional (slow) mode
           Bit 6 = Interrupt level:
                   0 = IRQ 7
                   1 = IRQ 5
           Bits 5-4 = Not used
           Bits 3-2 = Print device:
                      00 = LPT1
                      01 = LPT2
                      10 = LPT3
                      11 = Invalid
           Bits 1-0 = I/O port:
                      00 = 3BCH
                      01 = 378H
                      10 = 278H
                      11 = Other

         For Western Digital Ethernet:

           Bits 7 = I/O port address, bit 15
           Bits 6-4 = Not used
           Bits 3-0 = Interrupt level

         For Token Ring:

           Bit 7 = Buffer RAM size:
                   0 = 16K or more
                   1 = 8K
           Bits 6-4 = Not used
           Bits 3-0 = Interrupt level

         Compatibility note:  On the IBM PC Network Adapter, this byte
         indicates the setting of two jumpers on the card.  Bit 7=1 if
         the jumper labeled "W2" is on the adapter, and Bit 6=1 if the
         jumper labeled "W1" is on the adapter.

(1 byte) Status byte #2:

         For the old Model 300 series, the hardware interrupt level.

         For Ethernet or Token Ring, the number of aborted sessions.
         The counter rolls over from 0FFH to 0.

(2 bytes) Software version number (byte 0 = major, byte 1 = minor).

          Compatibility note:  On the IBM Token Ring Network, byte 0 is
          the software level number and byte 1 is always 0FFH.


Traffic and error statistics - 22 bytes:

(2 bytes) Reporting period (in minutes).  When the counter reaches
          0FFFFH, it rolls over to 0.

(2 bytes) Error counter #1:

          For the Model 300 series, the number of frames lost due to
          parity errors.  The counter does not increment past 0FFFFH.

          For Ethernet, the number of CRC errors.  The counter does not
          increment past 0FFFFH.

          For Token Ring, the number of times that the RECEIVE command
          failed and had to be re-issued, for reasons other than a
          missed packet.

          Compatibility note 1:  The IBM PC Network Adapter reports the
          number of received CRC errors here.

          Compatibility note 2:  The IBM Token Ring Network reports the
          number of FRMR frames received here, and the counter rolls
          over from 0FFFFH to 0.

(2 bytes) Error counter #2:

          For the Model 300 series, the number of received frames lost
          due to DMA overrun.  The counter does not increment past
          0FFFFH.

          For Ethernet, the number of alignment errors.  The counter
          does not increment past 0FFFFH.

          For Token Ring, the number of transmitted frames that were not
          copied by the intended destination station, either because the
          station was not on the network, or because the station's
          hardware buffer was full.

          Compatibility note 1:  The IBM PC Network Adapter reports the
          number of received alignment errors here.

          Compatibility note 2:  The IBM Token Ring Network reports the
          number of FRMR frames received here, and the counter rolls
          over from 0FFFFH to 0.

(2 bytes) Error counter #3:

          For the Model 300 series, the number of received frames that
          were discarded due to internal inconsistencies, such as an
          invalid network address or length.  The counter does not
          increment past 0FFFFH.

          For Ethernet, the number of collisions.  The counter does not
          increment past 0FFFFH.

          For Token Ring, this field is not used.

          Compatibility note 1:  The IBM PC Network Adapter reports the
          number of collisions here, and the counter rolls over from
          0FFFFH to 0.

          Compatibility note 2:  The IBM Token Ring Network reports the
          number of I-frames received in error here, and the counter
          rolls over from 0FFFFH to 0.

(2 bytes) Error counter #4:

          For the Model 300 series, the number of times the transmitter
          was squelched.  This can be caused by NetBIOS failing to
          respond to an interrupt quickly enough, or by a frame
          transmission failing to complete within the timeout interval.
          The counter does not increment past 0FFFFH.

          For Ethernet, the number of transmissions that were aborted
          due to excessive collisions.  The counter does not increment
          past 0FFFFH.

          For Token Ring, the number of TRANSMIT.DIR.FRAME commands that
          failed, for reasons other than frame not copied.

          Compatibility note:  The IBM PC Network and IBM Token Ring
          Network report the number of aborted transmissions here, and
          the counter rolls over from 0FFFFH to 0.

(4 bytes) Number of successfully transmitted frames.  The counter rolls
          over from 0FFFFFFFFH to 0.

(4 bytes) Number of successfully received frames.  The counter rolls
          over from 0FFFFFFFFH to 0.

(2 bytes) Retransmissions:

          The number of session frames that had to be retransmitted
          because the destination station did not respond in time.  The
          counter does not increment past 0FFFFH.

          Compatibility note 1:  The IBM PC Network Adapter reports the
          number of frames that had to be retransmitted due to
          collisions on the cable, and the counter rolls over from
          0FFFFH to 0.

          Compatibility note 2:  The IBM Token Ring Network reports the
          number of I-frames transmitted in error here, and the counter
          rolls over from 0FFFFH to 0.

(2 bytes) Error counter #5:

          For the Model 300 series, the number of times receiver
          exhausted its resources.  The counter does not increment past
          0FFFFH.

          For Ethernet (except Western Digital), the number of received
          frames discarded because the hardware receive buffer was
          full.  The counter does not increment past 0FFFFH.

          For Western Digital Ethernet, the high-order 10 bits of this
          field are bits 14-5 of the I/O port address (bit 15 of the I/O
          port address is in status byte #1, and bits 4-0 of the I/O
          port address are zero).  The low-order 6 bits of this field
          are bits 18-13 of the shared RAM memory address (bit 19 of the
          memory address is one, and bits 12-0 of the memory address are
          zero).

          For Token Ring, the number of received packets discarded
          because TransBIOS had no buffer space to store them.

          Compatibility note:  For the IBM PC Network, this count is the
          number of received frames that were discarded because no
          receive buffer was available.  For the IBM Token Ring Network,
          this count is the number of times the receive buffer was full.


Adapter resource statistics - 28 bytes:

(2 bytes) Error counter #6:

          For the Model 300 series, the number of transmit loopback
          errors.  Whenever the Model 300 transmits a frame, it compares
          the received data to the transmitted data.  If the two do not
          agree, a transmit loopback error occurs.  The counter rolls
          over from 0FFFFH to 0.

          For Ethernet, the low order byte is the number of received
          frames that were internally inconsistent.  The high byte is
          the number of times that the hardware's DMA channel was too
          slow.  These counters do not increment past 0FFH.

          For Token Ring, the low byte is the number of received frames
          that were internally inconsistent.  The high byte is the
          number of fatal ring status errors that required a reset of
          the Token Ring hardware.  These counters do not increment past
          0FFH.

          Compatibility note 1:  For the IBM PC Network, this is the
          number of free transmit data buffers.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the number of times the DLC T1 timer expired.

(2 bytes) Error counter #7:

          For the Model 300 series, the number of times that cable
          congestion was detected.  Whenever Model 300 transmits a
          frame, it must gain control of the network cable.  If this
          takes more than 150 milliseconds, then the cable is congested
          (i.e., network traffic is very heavy).  The counter rolls over
          from 0FFFFH to 0.

          For Ethernet, the number of times that the hardware receive
          buffer overflowed.  The counter does not increment past
          0FFFFH.

          For Token Ring, the low byte is the number of adapter status
          errors that required a reset of the hardware.  The high byte
          is the number of fatal PC-detected errors that required a
          reset of the hardware.  The counters do not increment past
          0FFH.

          Compatibility note 1:  For the IBM PC Network, this is the
          total number of transmit data buffers.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the number of times the DLC Ti timer expired.

(2 bytes) Error counter #8:

          For the Model 300 series, the number of sessions that were
          aborted.  The counter rolls over from 0FFFFH to 0.

          For Ethernet, the number of times that the Ethernet controller
          chip had to be reset.  This occurs if the on-board buffer RAM
          is corrupted, or if the controller chip appears to have
          malfunctioned.

          For Token Ring, this field is not used.

          Compatibility note 1:  For the IBM PC Network, this is the
          number of free receive data buffers.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the offset address of the extended status information.

(2 bytes) Time at which the last session abort occurred.  Whenever a
          session is aborted, the value of the Reporting Period counter
          is copied into this field.

          Compatibility note 1:  For the IBM PC Network, this is the
          total number of receive data buffers.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the segment address of the extended status information.

(2 bytes) Free command blocks:

          If obtaining status from the local station, this field
          contains the number of free NCBs.  If obtaining status from a
          remote station, this field contains zero.

          Compatibility note:  For the IBM PC Network and IBM Token Ring
          Network, this field always contains the number of free NCBs
          for the responding station.

(2 bytes) Configured command blocks:

          If obtaining status from the local station, this field
          contains the maximum number of NCBs that can be open at one
          time, as defined in the station's NET30.INI file.  If
          obtaining status from a remote station, this field contains
          zero.

          Compatibility note 1:  For the IBM PC Network and IBM Token
          Ring Network, this field always contains the configured
          maximum number of open NCBs for the responding station.

          Compatibility note 2:  For the IBM PC Network, this is the
          number of command blocks specified in the last RESET command.

          Compatibility note 3:  For the IBM Token Ring Network, this is
          the number of commands specified in the last DIR.OPEN.ADAPTER
          command or the last RESET command.

(2 bytes) Maximum command blocks:

          If obtaining status from the local station, this field
          contains the maximum number of NCBs that can be open at one
          time, as defined in the station's NET30.INI file.  If
          obtaining status from a remote station, this field contains
          zero.

          Compatibility note 1:  For the IBM PC Network and IBM Token
          Ring Network, this field always contains the maximum possible
          number of NCBs for the responding station.

          Compatibility note 1:  For the IBM PC Network, this is always
          32.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          always 255.

(2 bytes) Lost data frames:

          The number of out-of-sequence session data frames that were
          received.  This indicates that a previous session data frame
          was lost.  The counter does not increment past 0FFFFH.

          Compatibility note 1:  For the IBM PC Network, this is the
          number of free message blocks.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the number of times a local station went busy.

(2 bytes) Hardware type code:

            0000H - Invalid or not available.
            0001H - No hardware.
            0002H - Invisible Network Model 100, 200, or 300.
            0003H - Invisible Network Model 200/A or 300/A.
            0004H - Invisible Ethernet-8 with 32K RAM.
            0005H - Invisible Ethernet-16 with 16K RAM.
            0006H - Invisible Ethernet-16 with 64K RAM.
            0007H - Invisible Ethernet/A with 16K RAM.
            0008H - Invisible Ethernet/A with 64K RAM.
            000FH - NE-1000.
            0011H - NE-2000.
            0013H - NE/2.
            0015H - Invisible or Accton Parallel Port Ethernet.
            0016H - NE-1000 with 8390B controller chip.
            0017H - NE-2000 with 8390B controller chip.
            0018H - Invisible Ethernet 1000.
            0019H - Invisible Ethernet 2000.
            001AH - Western Digital 8003 with 8K RAM.
            001BH - Western Digital 8003 with 32K RAM.
            001CH - Western Digital 8013 with 16K RAM.
            001DH - Western Digital 8013 with 64K RAM.
            001EH - Invisible Ethernet 2/A.
            001FH - NE-1000 with D-Link controller chip.
            0020H - NE-2000 with D-Link controller chip.
            0023H - IBM Token Ring.

          Compatibility note 1:  For the IBM PC Network, this is the
          total number of message blocks.

          Compatibility note 2:  For the IBM Token Ring Network, this is
          the maximum datagram packet size.

(2 bytes) Number of sessions:

          The number of network sessions.  This includes all TransBIOS
          sessions, not just NetBIOS sessions.  Each established NetBIOS
          session and each pending NetBIOS CALL uses one TransBIOS
          session.  A pending NetBIOS LISTEN does not consume a
          TransBIOS session.

          Compatibility note:  For the IBM PC Network and IBM Token Ring
          Network, this number includes not only established sessions,
          but also pending CALL and LISTEN commands, as well as sessions
          that have been terminated where the session termination has
          not yet been reported to the user.

(2 bytes) Configured sessions:

          The maximum number of TransBIOS sessions that can be open at
          one time, as defined in the station's NET30.INI file.

          Compatibility note 1:  For the IBM PC Network and IBM Token
          Ring Network, this field contains the configured maximum
          number of NetBIOS sessions for the responding station.

          Compatibility note 2:  For the IBM PC Network, this is the
          number of sessions specified in the last RESET command.

          Compatibility note 3:  For the IBM Token Ring Network, this is
          the number of sessions specified in the last DIR.OPEN.ADAPTER
          command or the last RESET command.

(2 bytes) Maximum sessions:

          The maximum number of TransBIOS sessions that can be open at
          one time, as defined in the station's NET30.INI file.

          Compatibility note 1:  For the IBM PC Network and IBM Token
          Ring Network, this field contains the maximum possible number
          of NetBIOS sessions for the responding station.

          Compatibility note 2:  For the IBM PC Network, this is always
          32.

          Compatibility note 3:  For the IBM Token Ring Network, this is
          always 254.

(2 bytes) Recommended session data unit size.  Session data transfer is
          most efficient when the message size equals this number.

(2 bytes) Number of names in name table.  The permanent node name is not
          counted here.  The maximum possible number of names is
          determined by the station's NET30.INI file.

          Compatibility note:  For the IBM PC Network and IBM Token
          Ring Network, the number of names cannot exceed 16.


Local name table - 18 bytes per name:

(16 bytes) The name.  Note that the permanent node name will not appear
           here.

(1 byte) Name number.

(1 byte) Name status:

         Bit 7 = 1 for a group name, = 0 for a unique name.

         Bits 6-3 = reserved.

         Bit 2 = 1 if registered, = 0 if trying to register.

         Bit 1 = 1 if name is a detected duplicate.  Note that this bit
                   is set only in the case of an illegal duplication; it
                   is not set when a group name is registered at more
                   than one station.

         Bit 0 = 1 if name is de-registered.




4.4.  UNLINK


     UNLINK is effective only if the station was booted using the Remote
Program Load (RPL) feature.  UNLINK disconnects the INT 13H disk
redirector and closes the session with the IBMNETBOOT file server.  This
makes it possible for the station the access its local disk drives.
(While the disk redirector is active, the station cannot access its
local disk drives).

     If the station was not booted using the Remote Program Load
feature, or if an UNLINK command has already been issued, then UNLINK
performs no operation.

     Note 1:  The UNLINK command can be issued only in the wait form.

     Note 2:  In RAM-resident NetBIOS, the UNLINK command performs no
operation.


Fields Required:

NCB_COMMAND = 70H (Wait form).


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

21H = Interface busy.

40H-0FEH = Network malfunction.




4.5.  IDENTIFY


     This command can be used to obtain a list of all the stations on
the network.  The station executing an IDENTIFY command repeatedly sends
a query onto the network.  Upon receiving the queries, all other
stations send back responses identifying themselves.  The first response
received from each station is placed into the data buffer specified by
NCB_BUFFER.

     Note 1:  IDENTIFY generates a very large amount of traffic on the
network.  As a result, its use should be minimized.

     Note 2:  IDENTIFY is intended to be used for diagnostic purposes.
Avoid using IDENTIFY in ordinary application programs.

     Note 3:  The station will respond to its own queries, so there
should always be at least one response.

     Compatibility note:  IDENTIFY is not supported by the IBM PC
Network or IBM Token Ring Network.


Fields Required:

NCB_COMMAND = 77H (Wait form) or 0F7H (No-wait form).

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Length of data returned.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length.  Indicates that the buffer was not large
      enough to hold the entire list.  In this case, none of the data
      in the buffer is reliable.

03H = Invalid command.

05H = No responses were received.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.



Data returned:


(2 bytes) Number of stations responding.

(1 byte) Reserved.

(1 byte) Status.  For IDENTIFY, this is always 0FFH.


List of stations responding - 15 bytes per station:

(1 byte) Length of this list entry, not counting this byte.  For the
         Invisible LAN, this is always 14.

(2 bytes) Reserved.  Always zero.

(6 bytes) Unit identification number of the station issuing the IDENTIFY
          command.

          Note 1:  This will be the same in all entries.

          Note 2:  The unit identification number forms part of the
          permanent node name.  The 16-byte permanent node name consists
          of 10 bytes of binary zeros followed by the 6-byte unit
          identification number.

(6 bytes) Unit identification number of the responding station.

          Note:  The unit identification number forms part of the
          permanent node name.  The 16-byte permanent node name consists
          of 10 bytes of binary zeros followed by the 6-byte unit
          identification number.




4.6.  PRESENCE TEST


     Determine if a working network adapter is present in the computer.
On networks that allow more than one network adapter in the computer,
this command allows you to determine which network adapters are present.

     The network adapter whose presence you want to test is specified in
NCB_LANA_NUM.  If the adapter is present and working, error code 03H is
returned.  Any other return code indicates either that the adapter is
not present or that it is not working.

     Before issuing this command, you must check the contents of
interrupt vector 5CH at memory locations 0:170H-0:173H.  If it contains
all binary zeros, then no adapter is present.

     Note 1:  You should put 0FFH into NCB_RETCODE before issuing this
command.  It is recommended that you obtain the final return code from
the NCB_RETCODE field rather than the AL register.

     Note 2:  Although PRESENCE TEST has two different command codes, it
is always executed in the wait form.  NCB_POST is not used.  However, it
is recommended that you use command code 7FH (rather than 0FFH).


Fields Required:

NCB_COMMAND = 7FH or 0FFH (Wait form).  7FH is recommended.

NCB_RETCODE = 0FFH.

NCB_POST = Binary zeros (recommended but not required).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.  This should never happen.  If it happens, the
      adapter is present and working, but you are using an unusual
      version of NetBIOS.
      Note:  With the Invisible LAN, this will never happen.

03H = Invalid command.  This means the adapter is present and working.

23H = Invalid NCB_LANA_NUM.  This means the specified adapter is not
      present, but another adapter is present.

40H-0FEH = Network malfunction.  The adapter is present but not working.

0FFH = Command pending.  No adapter is present.




------------------------------------------------------------------------




5.  NAME SUPPORT COMMANDS


     Name support commands allow stations to be known by user-assigned
names such as "John" or "Mary".  Each name is 16 characters long.  All
16 characters are significant, and lower-case letters are considered to
be different than upper-case letters.

     There are two kinds of names:  unique names and group names.  A
unique name is a name that can be used by only one station on the
network.  Whenever you try to register a unique name for your station,
NetBIOS automatically checks to make sure that no other station is using
the name.  For example, if one station is using "John" as a unique name,
then no other station can use the name "John".

     A group name is a name that can be used by more than one station.
Whenever you try to register a group name for your station, NetBIOS
automatically checks to make sure that no other station is using the
name as a unique name;  it is permitted for other stations to be using
the name as a group name.  For example, the name "Accounting" could be
used as a group name by everyone in the accounting department.

     In addition to the user-assigned names, each station also has a
unique permanent node name.  The permanent node name consists of 10
bytes of binary zeros followed by the 6-byte unit identification number.
The unit identification number is the first 6 bytes of data returned by
the ADAPTER STATUS command.

     Thus, to find your station's permanent node name, you must issue an
ADAPTER STATUS command with a value of "*" in the NCB_CALLNAME field,
and append the first 6 bytes of data returned to 10 bytes of binary
zeros.  Note that the permanent node name does not appear in the local
name table returned by the ADAPTER STATUS command.

     Each name in the local name table has a one-byte name number
associated with it.  Some commands require you to refer to a name by
using the name number, while other commands require you to refer to a
name by using the name itself.  Name numbers are assigned in a
round-robin "Modulo 253" technique ranging from 2 to 254.  Name number 1
always refers to the permanent node name.  00H and 0FFH are never used
as name numbers.

     The RESET command deletes all names from the station except for the
permanent node name.

     Note 1:  You cannot add or delete any name whose first byte is "*"
or 00H.

     Note 2:  It is recommended that you not use any name starting with
IBM, MSNET, or ISI.

     Compatibility note:  For both the IBM PC Network and the IBM Token
Ring Network, a station can have a maximum of 16 names.  For Invisible
LAN, the maximum number of names is specified in the NET30.INI file.


     The following commands fall into the name support category:

     1.  ADD NAME - Register a unique name for your station.

     2.  ADD GROUP NAME - Register a group name for your station.

     3.  DELETE NAME - Remove a name from your local name table.

     4.  FIND NAME - Find all stations on the network which are using a
given name.




5.1.  ADD NAME


     Add the name specified in NCB_NAME to the local name table as a
unique name.  A unique name cannot be used by any other station on the
network.

     When NetBIOS gets this command, it repeatedly sends a query onto
the network.  If no response is received, the name is presumed to be
unique and is added to the table of names.  If a response is received,
NetBIOS returns error code 16H ("name in use on remote station") and
does not add the name to the table of names.

     When a name is added to the table of names, the corresponding name
number is returned in NCB_NUM.  The name number is used for RECEIVE ANY
commands and for datagram support.


Fields Required:

NCB_COMMAND = 30H (Wait form) or 0B0H (No-wait form).

NCB_NAME = 16-character name to be added to the name table.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_NUM = Name number.


Final Return Codes:

00H = Good return.

03H = Invalid command.

0DH = Duplicate name in local name table.

0EH = Name table is full.

15H = First byte of NCB_NAME is "*" or 00H.

16H = Name in use on remote station.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




5.2.  ADD GROUP NAME


     Add the name specified in NCB_NAME to the local name table as a
group name.  A group name cannot be used by any other station on the
network as a unique name, but can be used by other stations as a group
name.

     When NetBIOS gets this command, it repeatedly sends a query onto
the network.  If no response is received from a station using the name
as a unique name, the name is added to the table of names.  If a
response is received, NetBIOS return error code 16H ("name in use on
remote station") and does not add the name to the table of names.

     When a name is added to the table of names, the corresponding name
number is returned in NCB_NUM.  The name number is used for RECEIVE ANY
commands and for datagram support.


Fields Required:

NCB_COMMAND = 36H (Wait form) or 0B6H (No-wait form).

NCB_NAME = 16-character name to be added to the name table.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_NUM = Name number.


Final Return Codes:

00H = Good return.

03H = Invalid command.

0DH = Duplicate name in local name table.

0EH = Name table is full.

15H = First byte of NCB_NAME is "*" or 00H.

16H = Name in use on remote station.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




5.3.  DELETE NAME


     The name specified in NCB_NAME is removed from the local name
table.

     When this command is issued, any pending LISTEN, RECEIVE ANY,
RECEIVE DATAGRAM, and RECEIVE BROADCAST DATAGRAM commands associated
with the name are immediately terminated with an error code of 17H
("name was deleted").

     If the name has active sessions, the name is flagged as
de-registered and the DELETE NAME command is returned with an error code
of 0FH ("name de-registered").  In this case, the name continues to
occupy a slot in the local name table.  When all the name's active
sessions terminate, the name will be automatically removed from the
local name table.


Fields Required:

NCB_COMMAND = 31H (Wait form) or 0B1H (No-wait form).

NCB_NAME = 16-character name to be removed from the name table.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

0FH = Name has active sessions and is now de-registered.

15H = First byte of NCB_NAME is "*" or 00H.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




5.4.  FIND NAME


     Obtain a list of all the stations on the network that are using the
name specified in NCB_CALLNAME.  The list is constructed in the data
buffer specified by NCB_BUFFER.

     The station executing a FIND NAME command repeatedly sends a query
onto the network.  Each station that has the specified name registered
in its local name table will respond to the query with a message that
indicates whether the name is a unique name or a group name.

     If no responses are received, the FIND NAME command returns with an
error code of 05H ("command timed out").  If responses are received, the
first response from each station is placed into the buffer specified by
NCB_BUFFER.

     Compatibility note:  FIND NAME is not supported by the IBM PC
Network.  FIND NAME is supported by the IBM Token Ring Network.


Fields Required:

NCB_COMMAND = 78H (Wait form) or 0F8H (No-wait form).

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_CALLNAME = Name to be found.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Length of data returned.  This always equals (33*N)+4,
             where N is the number of stations responding.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length.  Indicates that the buffer was not large
      enough to hold the entire list.  In this case, none of the data
      in the buffer is reliable.

03H = Invalid command.

05H = No responses were received.  Indicates that the name is not in use
      anywhere on the network.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.



Data returned:


(2 bytes) Number of stations responding.  This will be greater than 1
          only if the name is a group name.

(1 byte) Reserved.

(1 byte) Name status:
         00H = Unique name.
         01H = Group name.


List of stations responding - 33 bytes per station:

(1 byte) Actual length of this list entry, not counting this byte.  This
         can range from 14 to 32.  For the Invisible LAN, this is
         always 14.

         Note:  The list entry always occupies 33 bytes of space in the
         buffer, even if this field is less than 32.  If this field is
         less than 32, then the trailing portion of the routing
         information field is not used.

(1 byte) Reserved.  Always zero.

         Compatibility note:  For the IBM Token Ring Network, this is
         the Access Control byte.

(1 byte) Reserved.  Always zero.

         Compatibility note:  For the IBM Token Ring Network, this is
         the Frame Control byte.

(6 bytes) Unit identification number of the station issuing the FIND
          NAME command.

          Note 1:  This will be the same in all list entries.

          Note 2:  The unit identification number forms part of the
          permanent node name.  The 16-byte permanent node name consists
          of 10 bytes of binary zeros followed by the 6-byte unit
          identification number.

(6 bytes) Unit identification number of the responding station.

          Note 1:  The unit identification number forms part of the
          permanent node name.  The 16-byte permanent node name consists
          of 10 bytes of binary zeros followed by the 6-byte unit
          identification number.

          Note 2:  If routing information is present, the most
          significant bit of the first byte is set to 1.  This bit is
          not part of the unit identification number;  applications
          should mask out this bit when reading this field.

(18 bytes) Routing information.  For the Invisible LAN, there is
           no routing information.

           Note:  The routing information field is always 18 bytes long,
           even if the actual length of the routing information is less
           than 18 bytes.  If the actual length of the routing
           information is less than 18 bytes, then the last few bytes of
           this field are not used.




------------------------------------------------------------------------




6.  SESSION SUPPORT COMMANDS


     A session (also known as a virtual circuit) is a reliable logical
connection between two stations on the network.  Once a session has been
established, the two stations can send and receive messages over the
session.  NetBIOS automatically performs extensive error-checking,
acknowledgements, and retransmissions to ensure that all messages sent
by one station are received by the other station.  When a session is no
longer needed, it can be closed.

     A session can be established between any two names on the network.
The names can be located on two different stations, or both names can be
located on the same station.  It is even possible for a single name to
establish a session with itself.

     Each of your station's sessions has a one-byte local session number
(LSN) associated with it.  Once a session has been established, you must
use the local session number to refer to it.  Local session numbers are
assigned in a round-robin "Modulo 254" technique ranging from 1 to 254.
00H and 0FFH are never used as local session numbers.

     It is possible for a given pair of names to establish more than one
session with each other.  If this is done, the sessions are
differentiated by the fact that they have different local session
numbers.

     The maximum number of sessions is specified in the NET30.INI file.
If you create a session between two names that are both located on your
station, the session will consume 2 entries in the local session table
(and therefore count as 2 of your possible sessions).  In this case, one
side of the session has one local session number associated with it, and
the other side of the session has a different local session number
associated with it.

     Compatibility note 1:  The IBM PC Network allows a maximum of 32
sessions.

     Compatibility note 2:  The IBM Token Ring Network allows a maximum
of 254 sessions (depending on the configuration of the adapter).


     The following commands fall into the session support category:

     1.  CALL - Open a session with a specified name.

     2.  LISTEN - Enable a specified name, or any name, to CALL you.

     3.  HANG UP - Close a session.

     4.  SEND - Send a message on a session.

     5.  CHAIN SEND - Send a message on a session, concatenating two
separate buffers to form a single message.

     6.  INCOMPLETE SEND - Send a partial message on a session, allowing
any number of buffers to be concatenated into a single message.

     7.  RECEIVE - Receive a message on a session.

     8.  CHAIN RECEIVE - Receive a message on a session, splitting the
message into two separate buffers.

     9.  RECEIVE ANY - Receive a message on any session for a specified
local name, or for any local name.

     10.  SESSION STATUS - Get status of all sessions for a specified
local name, or for any local name.




6.1.  CALL


     Open a session with the name specified in NCB_CALLNAME, using the
local name specified in NCB_NAME.  The name specified in NCB_CALLNAME
can be located on either the local station or a remote station.  Also,
you can establish more than one session with the same pair of names.

     In order for the CALL to succeed, the name specified in
NCB_CALLNAME must have a LISTEN command outstanding.  If the name does
not have a LISTEN command outstanding, the CALL will return error code
12H ("session open rejected").  If the name is not present on the
network, the CALL will return error code 14H ("no answer").

     When the CALL succeeds, the local session number (LSN) is returned
in NCB_LSN.  Local session numbers are assigned in a round-robin "Modulo
254" technique ranging from 1 to 254.  00H and 0FFH are never used as
local session numbers.

     NCB_RTO specifies a timeout to be used with all RECEIVE and CHAIN
RECEIVE commands for this session.  The timeout is measured in units of
500 milliseconds, with a value of 00H indicating that there is no
timeout.  Any RECEIVE or CHAIN RECEIVE which fails to complete within
this time will be aborted.

     NCB_STO specifies a timeout to be used with all SEND, CHAIN SEND,
and INCOMPLETE SEND commands for this session.  The timeout is measured
in units of 500 milliseconds, with a value of 00H indicating that there
is no timeout.  Any SEND, CHAIN SEND, or INCOMPLETE SEND which fails to
complete within this time will be aborted.  Note that if a SEND, CHAIN
SEND, or INCOMPLETE SEND is aborted, the session will be automatically
terminated.

     Note:  Invisible LAN igores the NCB_RTO and NCB_STO fields.
NetBIOS cannot perform any timeouts because all timeouts are processed
at the TransBIOS level.


Fields Required:

NCB_COMMAND = 10H (Wait form) or 90H (No-wait form).

NCB_CALLNAME = 16-character name that you are calling.

NCB_NAME = 16-character local name to use.

NCB_RTO = Timeout for all RECEIVE and CHAIN RECEIVE commands for this
          session, in units of 500 milliseconds.  A value of 00H means
          that there is no timeout.

NCB_STO = Timeout for all SEND, CHAIN SEND, and INCOMPLETE SEND commands
          for this session, in units of 500 milliseconds.  A value of
          00H means that there is no timeout.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LSN = Local session number for this session.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out (called name did not respond in time).

09H = No resource available.

0BH = Command canceled.

11H = Local session table full.

12H = Session open rejected (called name has no LISTEN outstanding).

14H = Called name did not answer (called name not present on network).

15H = Name specified in NCB_NAME is not in local name table.

18H = Session ended abnormally.

19H = Name conflict detected.

1AH = Incompatible remote device.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.2.  LISTEN


     Makes it possible to open a session with the name specified in
NCB_CALLNAME, using the local name specified in NCB_NAME.  The name
specified in NCB_CALLNAME can be located on either the local station or
a remote station.  Also, you can establish more than one session with
the same pair of names.  In order for the session to be opened, the name
specified in NCB_CALLNAME must issue a CALL command to the name
specified in NCB_NAME.

     If the first byte of NCB_CALLNAME is "*", the LISTEN command makes
it possible to open a session with any name that issues a CALL command
to the local name specified in NCB_NAME.  In this case, the name that
issued the CALL will be returned in NCB_CALLNAME.

     If several LISTEN commands are outstanding, they are organized into
two levels of priority:  LISTEN for a specific name has the highest
priority, and LISTEN for any name has the lowest priority.  Within each
level of priority, LISTEN commands are prioritized according to the
order in which they were issued, with the oldest commands having the
highest priority.  Whenever NetBIOS receives a CALL, it will open a
session using the highest-priority LISTEN command that can match the
CALL.

     Once a LISTEN command is issued, it remains pending until a
matching CALL is received.  The LISTEN command does not time out.  An
outstanding LISTEN command consumes an entry in the local session table,
and is reported by the SESSION STATUS command.

     When the LISTEN returns, the local session number (LSN) is returned
in NCB_LSN.  Local session numbers are assigned in a round-robin "Modulo
254" technique ranging from 1 to 254.  00H and 0FFH are never used as
local session numbers.

     NCB_RTO specifies a timeout to be used with all RECEIVE and CHAIN
RECEIVE commands for this session.  The timeout is measured in units of
500 milliseconds, with a value of 00H indicating that there is no
timeout.  Any RECEIVE or CHAIN RECEIVE which fails to complete within
this time will be aborted.

     NCB_STO specifies a timeout to be used with all SEND, CHAIN SEND,
and INCOMPLETE SEND commands for this session.  The timeout is measured
in units of 500 milliseconds, with a value of 00H indicating that there
is no timeout.  Any SEND, CHAIN SEND, or INCOMPLETE SEND which fails to
complete within this time will be aborted.  Note that if a SEND, CHAIN
SEND, or INCOMPLETE SEND is aborted, the session will be automatically
terminated.

     Error code 19H ("name conflict detected") is returned if NetBIOS
detects that more than one station has the local name specified in
NCB_NAME registered as a unique name.  All stations having that name,
except for the one where the LISTEN completes successfully, will receive
error 19H.

     Note:  Invisible LAN igores the NCB_RTO and NCB_STO fields.
NetBIOS cannot perform any timeouts because all timeouts are processed
at the TransBIOS level.


Fields Required:

NCB_COMMAND = 11H (Wait form) or 91H (No-wait form).

NCB_CALLNAME = 16-character name that you are listening for.  If the
               first byte is "*", then listen for a CALL from any name.

NCB_NAME = 16-character local name to use.

NCB_RTO = Timeout for all RECEIVE and CHAIN RECEIVE commands for this
          session, in units of 500 milliseconds.  A value of 00H means
          that there is no timeout.

NCB_STO = Timeout for all SEND, CHAIN SEND, and INCOMPLETE SEND commands
          for this session, in units of 500 milliseconds.  A value of
          00H means that there is no timeout.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LSN = Local session number for this session.

NCB_CALLNAME = 16-character name that issued the CALL.


Final Return Codes:

00H = Good return.

03H = Invalid command.

09H = No resource available.

0BH = Command canceled.

11H = Local session table full.

15H = Name specified in NCB_NAME is not in local name table.

17H = Name specified in NCB_NAME was deleted.

18H = Session ended abnormally.

19H = Name conflict detected.

1AH = Incompatible remote device.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.3.  HANG UP


     Close the session specified in NCB_LSN.

     When a HANG UP command is issued, all local RECEIVE and CHAIN
RECEIVE commands on the session are immediately terminated with error
code 0AH ("session closed").  This occurs regardless of whether or not
the the command had transferred any data.

     If there are no local SEND, CHAIN SEND, or INCOMPLETE SEND commands
on the session, then the session is immediately closed and the HANG UP
command is returned with error code 00H ("good return").

     If there are local SEND, CHAIN SEND, or INCOMPLETE SEND commands on
the session, the HANG UP will delay until the SEND, CHAIN SEND, and
INCOMPLETE SEND commands complete, or until approximately 20 seconds
have elapsed.  The delay will end if any of the following occur:

     1.  The SEND, CHAIN SEND, and INCOMPLETE SEND commands all
         complete.  If this happens, the session is immediately closed
         and the HANG UP is returned with error code 00H ("good
         return").

     2.  A SEND, CHAIN SEND, or INCOMPLETE SEND command aborts because
         it times out or is canceled.  If this happens, the session is
         immediately aborted and the HANG UP is returned with error code
         18H ("session ended abnormally").

     3.  The remote station issues a HANG UP command.  If this happens,
         the session is immediately closed and the HANG UP is returned
         with error code 00H ("good return").

     If none of the above occur within approximately 20 seconds after
the HANG UP command is issued, then the session is aborted and the HANG
UP is returned with error code 05H ("command timed out").

     When a session closes, all outstanding RECEIVE, CHAIN RECEIVE,
SEND, CHAIN SEND, and INCOMPLETE SEND commands on the session are
immediately returned with error code 0AH ("session closed").  In
addition, if there are any outstanding RECEIVE ANY commands for the
local name used by the session, then one (and only one) is returned with
error code 0AH ("session closed").  If there are no outstanding RECEIVE
ANY commands for the local name used by the session, but there are one
or more outstanding RECEIVE ANY commands for any name, then one (and
only one) is returned with error code 0AH ("session closed").

     When a session aborts, all outstanding commands on the session are
immediately returned with error code 18H ("session ended abnormally").
In addition, if there are any outstanding RECEIVE ANY commands for the
local name used by the session, then one (and only one) is returned with
error code 18H ("session ended abnormally").  If there are no
outstanding RECEIVE ANY commands for the local name used by the session,
but there are one or more outstanding RECEIVE ANY commands for any name,
then one (and only one) is returned with error code 18H ("session ended
abnormally").

     Compatibility notes:  The Invisible LAN's HANG UP command behaves
in the manner described above, which is in accordance with the IBM PC
Network Technical Reference Manual.  The are, however, two instances
where the HANG UP command on the IBM PC Network Adapter does not behave
in accordance with the Technical Reference Manual:

     1.  Suppose that stations A and B have a session, and A has an
outstanding SEND command.  Then station B issues a HANG UP command.  The
Technical Reference Manual states that the session should immediately
close, and the SEND command should be returned with "session closed"
error status.  In actuality, the IBM PC Network Adapter will immediately
abort the session and return the SEND with "session ended abnormally"
error status.

     2.  Suppose that A and B have a session, that A an outstanding SEND
command, and that B also has an outstanding SEND command.  Then A and B
both issue HANG UP commands.  The Technical Reference Manual says that
the session should immediately close, and both SEND commands should
return "session closed" error status.  In actuality, the IBM PC Network
Adapter will delay for approximately 20 seconds, then abort the session
and return both SEND commands with "session ended abnormally" error
status.


Fields Required:

NCB_COMMAND = 12H (Wait form) or 92H (No-wait form).

NCB_LSN = Local session number.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out (outstanding SEND, CHAIN SEND, and INCOMPLETE
      SEND commands did not complete in time).

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session already closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.4.  SEND


     Send a message on the session whose local session number (LSN) is
given in NCB_LSN.  The message is taken from the buffer pointed to by
NCB_BUFFER.  The length of the message is specified in NCB_LENGTH.  The
length can range from 0 to 65,535 bytes.

     If more than one SEND, CHAIN SEND, or INCOMPLETE SEND is pending on
a given session, they are processed in first-in, first-out order.

     If the SEND command does not complete within the timeout period
that was specified by the CALL or LISTEN command, the SEND is returned
with error code 05H ("command timed out") and the session is aborted.

     If the SEND command is canceled, the SEND is returned with error
code 0BH ("command canceled") and the session is aborted.

     If the remote station issues a HANG UP command, all outstanding
SEND commands on the session are returned with error code 0AH ("session
closed").  If the local station issues a HANG UP command, the HANG UP
delays until all outstanding SEND commands on the session are complete.
If the session is aborted, all outstanding SEND commands on the session
are returned with error code 18H ("session ended abnormally").  Refer to
the description of the HANG UP command for further information on
session termination.


Fields Required:

NCB_COMMAND = 14H (Wait form) or 94H (No-wait form).

NCB_LSN = Local session number.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out.

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.5.  CHAIN SEND


     Send a message on the session whose local session number (LSN) is
given in NCB_LSN.  The contents of two separate buffers are concatenated
to form a single message.  The length of the message can range from 0 to
131,070 bytes.

     The first part of message is taken from the buffer pointed to by
NCB_BUFFER.  The length of the first part of the message is specified in
NCB_LENGTH.  The second part of the message is taken from the buffer
specified in the first six bytes of NCB_CALLNAME;  the first two bytes
of NCB_CALLNAME give the length of the buffer, and the next four bytes
give the address of the buffer.  Each buffer can contain from 0 to
65,535 bytes of data.

     If more than one SEND, CHAIN SEND, or INCOMPLETE SEND is pending on
a given session, they are processed in first-in, first-out order.

     If the CHAIN SEND command does not complete within the timeout
period that was specified by the CALL or LISTEN command, the CHAIN SEND
is returned with error code 05H ("command timed out") and the session is
aborted.

     If the CHAIN SEND command is canceled, the CHAIN SEND is returned
with error code 0BH ("command canceled") and the session is aborted.

     If the remote station issues a HANG UP command, all outstanding
CHAIN SEND commands on the session are returned with error code 0AH
("session closed").  If the local station issues a HANG UP command, the
HANG UP delays until all outstanding CHAIN SEND commands on the session
are complete.  If the session is aborted, all outstanding CHAIN SEND
commands on the session are returned with error code 18H ("session ended
abnormally").  Refer to the description of the HANG UP command for
further information on session termination.


Fields Required:

NCB_COMMAND = 17H (Wait form) or 97H (No-wait form).

NCB_LSN = Local session number.

NCB_BUFFER = Address of first data buffer.

NCB_LENGTH = Length of first data buffer.

NCB_CALLNAME = Length and address of second data buffer.  The first two
               bytes of NCB_CALLNAME give the length of the second data
               buffer, and the next four bytes give the address of the
               second data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out.

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.6.  INCOMPLETE SEND


     Send a partial message on the session whose local session number
(LSN) is given in NCB_LSN.  The partial message is taken from the buffer
pointed to by NCB_BUFFER.  The length of the partial message is
specified in NCB_LENGTH.  The length can range from 0 to 65,535 bytes.

     The data specified by INCOMPLETE SEND is not a complete message.
The next SEND, CHAIN SEND, or INCOMPLETE SEND command issued on this
session will continue the same message.  To complete the message, you
must issue SEND or CHAIN SEND.  Thus, you can concatenate an unlimited
number of buffers to form a single message by issuing a series of
IMCOMPLETE SEND commands followed by a SEND or CHAIN SEND command.

     If more than one SEND, CHAIN SEND, or INCOMPLETE SEND is pending on
a given session, they are processed in first-in, first-out order.

     If the INCOMPLETE SEND command does not complete within the timeout
period that was specified by the CALL or LISTEN command, the INCOMPLETE
SEND is returned with error code 05H ("command timed out") and the
session is aborted.

     If the INCOMPLETE SEND command is canceled, the INCOMPLETE SEND is
returned with error code 0BH ("command canceled") and the session is
aborted.

     If the remote station issues a HANG UP command, all outstanding
INCOMPLETE SEND commands on the session are returned with error code 0AH
("session closed").  If the local station issues a HANG UP command, the
HANG UP delays until all outstanding INCOMPLETE SEND commands on the
session are complete.  If the session is aborted, all outstanding SEND
commands on the session are returned with error code 18H ("session ended
abnormally").  Refer to the description of the HANG UP command for
further information on session termination.

     Compatibility Note:  INCOMPLETE SEND is not supported by the IBM PC
Network or IBM Token Ring Network.


Fields Required:

NCB_COMMAND = 1AH (Wait form) or 9AH (No-wait form).

NCB_LSN = Local session number.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out.

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.7.  RECEIVE


     Receive a message on the session whose local session number is
given in NCB_LSN.  The data is placed into the buffer pointed to by
NCB_BUFFER.  The length of the buffer is specified in NCB_LENGTH.  If
the buffer is not large enough to hold the entire message, NetBIOS fills
the buffer with data and returns the RECEIVE command with error code 06H
("message incomplete");  in this case, the remainder of the message can
be obtained by issuing another RECEIVE, CHAIN RECEIVE, or RECEIVE ANY
command.

     On return, NCB_LENGTH is updated to indicate the number of data
bytes that were placed into the buffer.

     Receive-type commands are organized into three levels of priority:
RECEIVE and CHAIN RECEIVE have the highest priority, RECEIVE ANY for a
specific name has the second highest priority, and RECEIVE ANY for any
name has the lowest priority.  Within each level of priority, commands
are prioritized according to the order in which they were issued, with
the oldest commands having the highest priority.  Whenever NetBIOS
receives a message, it will use the highest-priority receive-type
command that can accept the message.

     If the RECEIVE command does not complete within the timeout period
that was specified by the CALL or LISTEN command, the RECEIVE is
returned with error code 05H ("command timed out").

     When a session closes, all outstanding RECEIVE commands on the
session are returned with error code 0AH ("session closed").  When a
session aborts, all outstanding RECEIVE commands on the session are
returned with error code 18H ("session ended abnormally").  Refer to the
description of the HANG UP command for further information on session
termination.


Fields Required:

NCB_COMMAND = 15H (Wait form) or 95H (No-wait form).

NCB_LSN = Local session number.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Number of data bytes that were placed into the buffer.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out.

06H = Message incomplete.

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.8.  CHAIN RECEIVE


     Receive a message on the session whose local session number is
given in NCB_LSN.  Two buffers are specified with this command.  If the
first buffer is large enough to hold the entire message, the entire
message is placed into the first buffer and the second buffer is not
used.  If the first buffer is not large enough to hold the entire
message, NetBIOS fills the first buffer with data and places the rest of
the message into the second buffer.  If both buffers together are not
large enough to hold the entire message, NetBIOS fills both buffers with
data and returns the CHAIN RECEIVE with error code 06H ("message
incomplete");  in this case, the remainder of the message can be
obtained by issuing another RECEIVE, CHAIN RECEIVE, or RECEIVE ANY
command.

     The address of the first buffer is specified in NCB_BUFFER.  The
length of the first buffer is specified in NCB_LENGTH.  The length and
address of the second buffer are specified in the first six bytes of
NCB_CALLNAME;  the first two bytes of NCB_CALLNAME give the length of
the second buffer, and the next four bytes give the address of the
second buffer.

     On return, NCB_LENGTH is updated to indicate the number of data
bytes that were placed into the first buffer, and the first two bytes of
NCB_CALLNAME are updated to indicate the number of data bytes that were
placed into the second buffer.

     Receive-type commands are organized into three levels of priority:
RECEIVE and CHAIN RECEIVE have the highest priority, RECEIVE ANY for a
specific name has the second highest priority, and RECEIVE ANY for any
name has the lowest priority.  Within each level of priority, commands
are prioritized according to the order in which they were issued, with
the oldest commands having the highest priority.  Whenever NetBIOS
receives a message, it will use the highest-priority receive-type
command that can accept the message.

     If the CHAIN RECEIVE command does not complete within the timeout
period that was specified by the CALL or LISTEN command, the CHAIN
RECEIVE is returned with error code 05H ("command timed out").

     When a session closes, all outstanding CHAIN RECEIVE commands on
the session are returned with error code 0AH ("session closed").  When a
session aborts, all outstanding CHAIN RECEIVE commands on the session
are returned with error code 18H ("session ended abnormally").  Refer to
the description of the HANG UP command for further information on
session termination.

     Compatibility note:  CHAIN RECEIVE is not supported by the IBM PC
Network or IBM Token Ring Network.


Fields Required:

NCB_COMMAND = 18H (Wait form) or 98H (No-wait form).

NCB_LSN = Local session number.

NCB_BUFFER = Address of first data buffer.

NCB_LENGTH = Length of first data buffer.

NCB_CALLNAME = Length and address of second data buffer.  The first two
               bytes of NCB_CALLNAME give the length of the second data
               buffer, and the next four bytes give the address of the
               second data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Number of data bytes placed into the first data buffer.

NCB_CALLNAME first two bytes = Number of data bytes placed into the
                               second data buffer.


Final Return Codes:

00H = Good return.

03H = Invalid command.

05H = Command timed out.

06H = Message incomplete.

08H = Illegal local session number (session was already terminated or
      never existed).

0AH = Session closed.

0BH = Command canceled.

18H = Session ended abnormally.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.9.  RECEIVE ANY


     Receive a message on any session for the specified local name.  The
local name is specified by putting its name number into NCB_NUM.

     The data is placed into the buffer pointed to by NCB_BUFFER.  The
length of the buffer is specified in NCB_LENGTH.  If the buffer is not
large enough to hold the entire message, NetBIOS fills the buffer with
data and returns the RECEIVE ANY command with error code 06H ("message
incomplete");  in this case, the remainder of the message can be
obtained by issuing another RECEIVE, CHAIN RECEIVE, or RECEIVE ANY
command.

     On return, NCB_LENGTH is updated to indicate the number of data
bytes that were placed into the buffer, and NCB_LSN is updated to
indicate the local session number of the session on which data was
received.

     If you put 0FFH into NCB_NUM, the RECEIVE ANY command will receive
a message on any session for any of your local names.  In this case,
NCB_NUM will be updated on return to indicate the name number of the
local name for which data was received.

     Receive-type commands are organized into three levels of priority:
RECEIVE and CHAIN RECEIVE have the highest priority, RECEIVE ANY for a
specific name has the second highest priority, and RECEIVE ANY for any
name has the lowest priority.  Within each level of priority, commands
are prioritized according to the order in which they were issued, with
the oldest commands having the highest priority.  Whenever NetBIOS
receives a message, it will use the highest-priority receive-type
command that can accept the message.

     The RECEIVE ANY command does not time out.

     When a session terminates, if there are any outstanding RECEIVE ANY
commands for the local name used by the session, then one (and only one)
is returned with error code 0AH ("session closed") or 18H ("session
ended abnormally").  If there are no outstanding RECEIVE ANY commands
for the local name used by the session, but there are one or more
outstanding RECEIVE ANY commands for any name, then one (and only one)
is returned with error code 0AH ("session closed") or 18H ("session
ended abnormally").  In either case, the NCB_LSN field is updated to
indicate the local session number of the session that terminated.  Refer
to the description of the HANG UP command for further information on
session termination.

     Note:  It is recommended that you not use RECEIVE ANY for any name,
because this command can receive messages that are intended for other
programs running in the computer.


Fields Required:

NCB_COMMAND = 16H (Wait form) or 96H (No-wait form).

NCB_NUM = Name number of the name for which you want to receive.  If
          this field equals 0FFH, then receive for any of your names.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LSN = Local session number of session on which data was received.

NCB_NUM = Name number of local name for which data was received.

NCB_LENGTH = Number of data bytes that were placed into the buffer.


Final Return Codes:

00H = Good return.

03H = Invalid command.

06H = Message incomplete.

0AH = Session closed.

0BH = Command canceled.

13H = Illegal name number in NCB_NUM.

17H = Name deleted.

18H = Session ended abnormally.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




6.10.  SESSION STATUS


     Receive the status of all pending sessions for the local name
specified in NCB_NAME.  If the first byte of NCB_NAME contains "*", then
you will receive the status of all pending sessions for any of your
local names (i.e., all pending sessions on the local station).

     The status information is placed into the buffer specified by
NCB_BUFFER, and the length of the status information is returned in
NCB_LENGTH.

     The buffer length required to receive all the status information is
4 bytes plus 36 bytes for each pending session.  If the buffer length is
too small, error code 06H ("message incomplete") is returned, as much
data as possible is placed in the buffer, and the remaining data is
lost.

     Compatibility note:  The IBM PC Network Technical Reference Manual
states that if the buffer is too small then error code 06H ("message
incomplete") should be returned, as described above.  However, in this
circumstance the IBM PC Network Adapter will actually return error code
01H ("illegal buffer length"), and no status information at all is
placed into the buffer.


Fields Required:

NCB_COMMAND = 34H (Wait form) or 0B4H (No-wait form).

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_NAME = Name for which status is desired, or "*" for all names.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Length of status data returned.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length.

03H = Invalid command.

06H = Message incomplete.

15H = Invalid name in NCB_NAME.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.



Data returned:


Name status - 4 bytes:

(1 byte) Name number of name specified in NCB_NAME.  If NCB_NAME is "*",
         this byte contains 0FFH.

(1 byte) Number of sessions with the local name specified in NCB_NAME.
         If NCB_NAME is "*", this is the total number of sessions on
         the local station.

(1 byte) Number of outstanding RECEIVE DATAGRAM and RECEIVE BROADCAST
         DATAGRAM commands.  See note 1 below.

(1 byte) Number of outstanding RECEIVE ANY commands.  See note 2 below.


Session status - 36 bytes for each session:

(1 byte) Local session number.

(1 byte) State of the session.  See note 3 below.
         01H = LISTEN pending.
         02H = CALL pending.
         03H = Session established.
         04H = HANG UP pending.
         05H = Session closed.
         06H = Session aborted.

(16 bytes) Local name.

(16 bytes) Remote name.

(1 byte) Number of RECEIVE and CHAIN RECEIVE commands outstanding.

(1 byte) Number of SEND, CHAIN SEND, and INCOMPLETE SEND commands
         outstanding.


     Note 1:  If NCB_NAME is "*", the third byte of the status
information contains the total number of outstanding RECEIVE DATAGRAM
commands on the station, plus the total number of outstanding RECEIVE
BROADCAST DATAGRAM commands on the station.  If NCB_NAME is not "*", the
third byte of the status information contains the number of outstanding
RECEIVE DATAGRAM commands for the name specified in NCB_NAME, plus the
number of outstanding RECEIVE DATAGRAM commands for any name, plus the
total number of outstanding RECEIVE BROADCAST DATAGRAM commands on the
station.

     Note 2:  If NCB_NAME is "*", the fourth byte of the status
information contains the total number of outstanding RECEIVE ANY
commands on the station.  If NCB_NAME is not "*", the fourth byte of the
status information contains the number of outstanding RECEIVE ANY
commands for the name specified in NCB_NAME, plus the number of
outstanding RECEIVE ANY commands for any name.

     Note 3:  When a session closes or aborts, it remains in the local
session table until the session termination is reported to the user.
This is why it is possible for SESSION STATUS to list a session that has
already terminated.  A terminated session is automatically removed from
the local session table when termination is reported to the user, i.e.,
when some command is returned with "session closed" or "session ended
abnormally" error status.  Note that being listed in the SESSION STATUS
information does not cause a terminated session to be removed from the
local session table.




------------------------------------------------------------------------




7.  DATAGRAM SUPPORT COMMANDS


     Datagram support commands allow you to send and receive messages
without using sessions.  Datagrams are typically used to implement
broadcast facilities.

     The size of a datagram is limited to a maximum of 512 bytes.

     Datagram support differs from session support in that datagram
transmissions are not reliable.  When you send a datagram, NetBIOS does
not guarantee that it will be received.  As a result, it is the
responsibility of the application program to perform any desired
acknowledgements and retransmissions.  Also, datagrams may be received
in an order different from the order in which they were sent.


     The commands that fall into the datagram support category are:

     1.  SEND DATAGRAM - Send a datagram to a specified name.

     2.  SEND BROADCAST DATAGRAM - Send a broadcast datagram.

     3.  RECEIVE DATAGRAM - Receive a datagram for a specified local
name, or for any local name.

     4.  RECEIVE BROADCAST DATAGRAM - Receive a broadcast datagram for a
specified local name, or for any local name.




7.1.  SEND DATAGRAM


     Send a datagram to the name specified in NCB_CALLNAME.  The name
can be either a unique name or a group name.  If the name is a group
name, it is possible for several different stations to receive the
datagram.  If the name is registered on the local station, it is
possible for the local station to receive its own datagram.

     The data is taken from the buffer pointed to by NCB_BUFFER.  The
length of the data is specified in NCB_LENGTH.  The length can range
from 0 to 512 bytes.  If NCB_LENGTH is greater than 512, the SEND
DATAGRAM is returned with error status 01H ("illegal buffer length").

     You must use one of your local names as the sender of the datagram.
The name number for the local name must be put into NCB_NUM.

     In order for a station to receive the datagram, it must have a
RECEIVE DATAGRAM command outstanding.  A station that does not have a
RECEIVE DATAGRAM outstanding at the time the SEND DATAGRAM is issued
will not receive the datagram.


Fields Required:

NCB_COMMAND = 20H (Wait form) or 0A0H (No-wait form).

NCB_NUM = Name number of the local name that is sending the datagram.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_CALLNAME = Name to which datagram is to be sent.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length (NCB_LENGTH greater than 512).

03H = Invalid command.

13H = Illegal name number in NCB_NUM.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




7.2.  SEND BROADCAST DATAGRAM


     Send a broadcast datagram to everyone who has an outstanding
RECEIVE BROADCAST DATAGRAM command.  If the local station has a RECEIVE
BROADCAST DATAGRAM command outstanding, it will receive its own
broadcast datagram.  If a given station has several RECEIVE BROADCAST
DATAGRAM commands outstanding, all of the outstanding commands will
receive the broadcast datagram.

     The data is taken from the buffer pointed to by NCB_BUFFER.  The
length of the data is specified in NCB_LENGTH.  The length can range
from 0 to 512 bytes.  If NCB_LENGTH is greater than 512, the SEND
DATAGRAM is returned with error status 01H ("illegal buffer length").

     You must use one of your local names as the sender of the broadcast
datagram.  The name number for the local name must be put into NCB_NUM.

     In order for a station to receive the broadcast datagram, it must
have a RECEIVE BROADCAST DATAGRAM command outstanding.  A station that
does not have a RECEIVE BROADCAST DATAGRAM outstanding at the time the
SEND BROADCAST DATAGRAM is issued will not receive the broadcast
datagram.


Fields Required:

NCB_COMMAND = 22H (Wait form) or 0A2H (No-wait form).

NCB_NUM = Name number of the local name that is sending the datagram.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.


Final Return Codes:

00H = Good return.

01H = Illegal buffer length (NCB_LENGTH greater than 512).

03H = Invalid command.

13H = Illegal name number in NCB_NUM.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




7.3.  RECEIVE DATAGRAM


     Receive a datagram from any station that sends a datagram to the
specified local name.  The local name is specified by putting its name
number into NCB_NUM.

     The data is placed into the buffer pointed to by NCB_BUFFER.  The
length of the buffer is specified in NCB_LENGTH.  There is no limit on
the value of NCB_LENGTH, but you will never receive more than 512 bytes
of data.  If the buffer is not large enough to hold the entire message,
NetBIOS fills the buffer with data and returns the RECEIVE DATAGRAM
command with error code 06H ("message incomplete");  in this case, the
remainder of the message is lost.

     On return, NCB_LENGTH is updated to indicate the number of data
bytes that were placed into the buffer, and NCB_CALLNAME is updated to
indicate the name that sent the datagram.

     If you put 0FFH into NCB_NUM, the RECEIVE DATAGRAM command will
receive a datagram from any station that sends a datagram to any of your
local names.  In this case, NCB_NUM will be updated on return to
indicate the name number of the local name that received the datagram.

     If several RECEIVE DATAGRAM commands are outstanding, they are
organized into two levels of priority:  RECEIVE DATAGRAM for a specific
name has the highest priority, and RECEIVE DATAGRAM for any name has the
lowest priority.  Within each level of priority, RECEIVE DATAGRAM
commands are prioritized according to the order in which they were
issued, with the oldest commands having the highest priority.  Whenever
NetBIOS receives a datagram, it will return the highest-priority RECEIVE
DATAGRAM command that can accept the datagram.

     If you do not have a RECEIVE DATAGRAM command outstanding at the
time a SEND DATAGRAM is issued, you will not receive the datagram.

     The RECEIVE DATAGRAM command does not time out.

     The RECEIVE DATAGRAM command will not receive a datagram that is
sent by a SEND BROADCAST DATAGRAM command.

     Note:  The RECEIVE DATAGRAM command behaves differently from the
RECEIVE BROADCAST DATAGRAM command.  If you have several RECEIVE
DATAGRAM commands outstanding when a SEND DATAGRAM is issued, only one
of your RECEIVE DATAGRAM commands is returned.  However, if you have
several RECEIVE BROADCAST DATAGRAM commands outstanding when a SEND
BROADCAST DATAGRAM is issued, all of your RECEIVE BROADCAST DATAGRAM
commands are returned.


Fields Required:

NCB_COMMAND = 21H (Wait form) or 0A1H (No-wait form).

NCB_NUM = Name number of the name for which you want to receive a
          datagram.  If this field equals 0FFH, then receive a datagram
          for any of your names.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_NUM = Name number of name for which datagram was received.

NCB_LENGTH = Number of data bytes that were placed into the buffer.

NCB_CALLNAME = Name that sent the datagram.


Final Return Codes:

00H = Good return.

03H = Invalid command.

06H = Message incomplete.

0BH = Command canceled.

13H = Illegal name number in NCB_NUM.

17H = Name deleted.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




7.5.  RECEIVE BROADCAST DATAGRAM


     Receive a broadcast datagram from any station that issues a SEND
BROADCAST DATAGRAM command.  You must specify which local name is to
receive the broadcast datagram by putting its name number into NCB_NUM.

     The data is placed into the buffer pointed to by NCB_BUFFER.  The
length of the buffer is specified in NCB_LENGTH.  There is no limit on
the value of NCB_LENGTH, but you will never receive more than 512 bytes
of data.  If the buffer is not large enough to hold the entire message,
NetBIOS fills the buffer with data and returns the RECEIVE BROADCAST
DATAGRAM command with error code 06H ("message incomplete");  in this
case, the remainder of the message is lost.

     On return, NCB_LENGTH is updated to indicate the number of data
bytes that were placed into the buffer, and NCB_CALLNAME is updated to
indicate the name that sent the broadcast datagram.

     If you put 0FFH into NCB_NUM, the RECEIVE BROADCAST DATAGRAM
command will receive a broadcast datagram for any of your local names.

     If you do not have a RECEIVE BROADCAST DATAGRAM command outstanding
at the time a SEND BROADCAST DATAGRAM is issued, you will not receive
the broadcast datagram.

     The RECEIVE BROADCAST DATAGRAM command does not time out.

     The RECEIVE BROADCAST DATAGRAM command will not receive a datagram
that is sent by a SEND DATAGRAM command.

     Note:  The RECEIVE DATAGRAM command behaves differently from the
RECEIVE BROADCAST DATAGRAM command.  If you have several RECEIVE
DATAGRAM commands outstanding when a SEND DATAGRAM is issued, only one
of your RECEIVE DATAGRAM commands is returned.  However, if you have
several RECEIVE BROADCAST DATAGRAM commands outstanding when a SEND
BROADCAST DATAGRAM is issued, all of your RECEIVE BROADCAST DATAGRAM
commands are returned.

     Compatibility note:  The IBM PC Network and IBM Token Ring Network
do not allow the use of NCB_NUM = 0FFH for RECEIVE BROADCAST DATAGRAM.


Fields Required:

NCB_COMMAND = 23H (Wait form) or 0A3H (No-wait form).

NCB_NUM = Name number of the name for which you want to receive a
          broadcast datagram.  If this field equals 0FFH, then receive a
          broadcast datagram for any of your names.

NCB_BUFFER = Address of data buffer.

NCB_LENGTH = Length of data buffer.

NCB_POST = Address of post routine (if no-wait command form is used).

NCB_LANA_NUM = Adapter number.


Fields Returned:

NCB_RETCODE = Final return code.

NCB_LENGTH = Number of data bytes that were placed into the buffer.

NCB_CALLNAME = Name that sent the broadcast datagram.


Final Return Codes:

00H = Good return.

03H = Invalid command.

06H = Message incomplete.

0BH = Command canceled.

13H = Illegal name number in NCB_NUM.

17H = Name deleted.

19H = Name conflict detected.

21H = Interface busy.

22H = Too many commands outstanding.

23H = Invalid NCB_LANA_NUM.

40H-0FEH = Network malfunction.




------------------------------------------------------------------------




8.  ERROR CODES


     The following is a list of the error codes that may be returned in
response to an NCB.  Codes 00H-3FH are errors that may occur during
normal operation.  Codes 40H-0FEH are fatal errors which make continued
operation impossible.

     For each error code, there is an explanation and a recommended
action.




00H = Good return (command completed successfully).

Explanation:

     The command is complete, and no error occurred.

Recommended action:

     None.




01H = Illegal buffer length.

Explanation:

     For SEND DATAGRAM or SEND BROADCAST DATAGRAM, the buffer length is
larger than 512.  For IDENTIFY or FIND NAME, the buffer is too short to
contain the entire list of responding stations.

     Compatibility note:  For ADAPTER STATUS or SESSION STATUS, the IBM
PC Network will produce this error if the buffer is too small to hold
the status data.

Recommended action:

     Specify the correct buffer size and retry the command.




03H = Invalid command.

Explanation:

     The command code in NCB_COMMAND is invalid.

     Note:  For PRESENCE TEST, this error code indicates that the
adapter is present and working.

Recommended action:

     Use the correct command code.




05H = Command timed out.

Explanation:

     For ADAPTER STATUS or FIND NAME, the name was not found on the
network.  For IDENTIFY, there were no responses.  For CALL, contact with
the remote station was lost partway through the process of opening a
session.  For HANG UP, pending SEND, CHAIN SEND, or INCOMPLETE SEND
commands did not complete within the 20-second timeout interval.  For
SEND, CHAIN SEND, INCOMPLETE SEND, RECEIVE, or CHAIN RECEIVE, the
command did not complete within the timeout interval that was specified
by CALL or LISTEN.

Recommended action:

     For ADAPTER STATUS or FIND NAME, make sure you are using the
correct name.  For IDENTIFY, retry the command.  For CALL, try again
later.  For RECEIVE or CHAIN RECEIVE, retry the command.  For SEND,
CHAIN SEND, INCOMPLETE SEND, or HANG UP, the session has been aborted;
the only possible action is to establish another session and try again.




06H = Message incomplete (buffer too short to receive entire message).

Explanation:

     You received part of the message because the buffer is not big
enough to receive the entire message.

Recommended action:

     For RECEIVE, CHAIN RECEIVE, or RECEIVE ANY, you can get the rest of
the message by issuing another RECEIVE, CHAIN RECEIVE, or RECEIVE ANY.
For ADAPTER STATUS, SESSION STATUS, RECEIVE DATAGRAM or RECEIVE
BROADCAST DATAGRAM, the remaining data is lost.




08H = Illegal local session number.

Explanation:

     The local session number is invalid.  The session already
terminated or never existed.

Recommended action:

     Use the correct local session number.




09H = No resource available for CALL or LISTEN (cannot create a new
      session).

Explanation:

     NetBIOS does not have the resources it needs to create a new
session.

     Note:  On the Invisible LAN, this error cannot occur.

Recommended action:

     Retry the CALL or LISTEN later.




0AH = Session closed.

Explanation:

     The HANG UP, SEND, CHAIN SEND, INCOMPLETE SEND, RECEIVE, CHAIN
RECEIVE, or RECEIVE ANY command cannot be completed because the session
is closed.

Recommended action:

     None.




0BH = Command canceled.

Explanation:

     The command was canceled by the CANCEL command.  If the command is
a SEND, CHAIN SEND, or INCOMPLETE SEND, the session is aborted.

Recommended action:

     None.




0DH = Duplicate name in local name table.

Explanation:

     For ADD NAME or ADD GROUP NAME, you tried to add a name which is
already in the local name table.

Recommended action:

     For ADD NAME or ADD GROUP NAME, use another name.




0EH = Name table full (cannot add any more names).

Explanation:

     An ADD NAME or ADD GROUP NAME failed because the local name table
already contains the maximum allowed number of names (16).

Recommended action:

     Delete an existing name to make room for the new name.




0FH = DELETE NAME specified a name that has active sessions (name is
      de-registered and unusable; will be deleted when sessions close).

Explanation:

     A DELETE NAME command specified a name that has active sessions.
The name is marked de-registered, and continues to occupy a slot in the
local name table.  No new commands can be issued using this name.

Recommended action:

     None.  The name will be automatically removed from the local name
table when all its sessions are terminated.




11H = Local session table full (cannot create new session).

Explanation:

     A CALL or LISTEN cannot be executed because the station already has
the maximum allowed number of pending sessions.

Recommended action:

     Terminate an existing session to make room for the new one.

     Note:  On the Invisible LAN, the maximum allowed number of sessions
is determined by the NET30.INI file.  On the IBM PC Network, the maximum
is specified in the RESET command (but it cannot exceed 32).  On the IBM
Token Ring Network, the maximum is specified in either the RESET command
or the DIR.OPEN.ADAPTER command (but it cannot exceed 254).




12H = Session open rejected (no LISTEN outstanding on remote station).

Explanation:

     The CALL command failed because the remote station does not have an
outstanding LISTEN command.

Recommended action:

     Wait until the remote station issues a LISTEN command, then retry
the CALL.




13H = Illegal name number.

Explanation:

     You specified a name number which does not correspond to any name
that is currently in your local name table.

Recommended action:

     Use the correct name number.




14H = Cannot find name or no answer (NCB_CALLNAME specified a name that
      could not be found or did not respond).

Explanation:

     A CALL failed because the name being called is not present on the
network.

Recommended action:

     Make sure you are using the correct name, and retry the CALL later.




15H = Name not found, or cannot specify "*" or 00H (name not in name
      table, or name begins with "*" or 00H).

Explanation:

     For ADD NAME, ADD GROUP NAME, or DELETE NAME, you specified a name
whose first byte contains "*" or 00H.  For DELETE NAME, CALL, LISTEN, or
SESSION STATUS, you specified a local name that is not in the local name
table.

Recommended action:

     Use the correct name and retry the command.




16H = Name in use on remote node.

Explanation:

     For ADD NAME, you specified a name which is being used by another
station.  For ADD GROUP NAME, you specified a name which is being used
as a unique name by another station.

Recommended action:

     Use another name.




17H = Name deleted.

Explanation:

     For LISTEN, RECEIVE ANY, RECEIVE DATAGRAM or RECEIVE BROADCAST
DATAGRAM, the specified local name was deleted while the command was
outstanding.

Recommended action:

     None.




18H = Session ended abnormally.

Explanation:

     The session was aborted.  This will happen if the cable is broken,
or if the remote station crashes, is reset, or is powered off.  It will
also happen if a SEND, CHAIN SEND, or INCOMPLETE SEND command times out
or is canceled, or if a HANG UP command times out waiting for an
outstanding SEND, CHAIN SEND, or INCOMPLETE SEND to complete.

Recommended action:

     Make sure that the cable is connected and the remote station is
running.  Reestablish the session.




19H = Name conflict detected.

Explanation:

     NetBIOS has detected a unique name that is being used by more than
one station on the network.

     Note:  In the Invisible LAN, only the FIND NAME command can detect
a name conflict.  Even in the IBM PC Network, name conflict detection is
only partially implemented.

Recommended action:

     All stations should delete the name.




1AH = Incompatible remote device.

Explanation:

     You attempted to open a session with a device that is not
compatible with NetBIOS.

Recommended action:

     Don't do that.




21H = Interface busy.

Explanation:

     You attempted to call NetBIOS from inside an interrupt handler.

Recommended action:

     Return from the interrupt handler and retry the command later.




22H = Too many commands outstanding.

Explanation:

     You cannot issue another command because you already have the
maximum allowed number of commands outstanding.

Recommended action:

     Wait for an outstanding command to complete before issuing another
command.

     Note:  On the Invisible LAN, the maximum allowed number of
outstanding commands is always 32.  On the IBM PC Network, the maximum
is specified in the RESET command (but it cannot exceed 32).  On the IBM
Token Ring Network, the maximum is specified in either the RESET command
or the DIR.OPEN.ADAPTER command (but it cannot exceed 255).




23H = Invalid number in NCB_LANA_NUM, or adapter not present.

Explanation:

     NCB_LANA_NUM did not contain the value 00H.

Recommended action:

     Retry the command with NCB_LANA_NUM set to 00H.

     Compatibility note:  Networks that allow more than one network
adapter to be present in the computer use NCB_LANA_NUM to specify which
adapter to use.  For these networks, error 23H indicates that the
specified adapter is not installed in the computer.




24H = Attempt to cancel a command that has already completed or never
      existed.

Explanation:

     For CANCEL, you specified a command that has already completed or
never was issued.

Recommended action:

     For a command that has already completed, none.  For a command that
was never issued, retry the CANCEL using the correct NCB address.




26H = Command not valid to cancel.

Explanation:

     You tried to cancel a RESET, CANCEL, UNLINK, IDENTIFY, ADD NAME,
ADD GROUP NAME, DELETE NAME, FIND NAME, SESSION STATUS, SEND DATAGRAM,
or SEND BROADCAST DATAGRAM command.

Recommended action:

     Don't do that.




40H-0FEH = Network malfunction.

Explanation:

     The network hardware has malfunctioned.  Continued operation of the
network adapter is not possible.

Recommended action:

     Reset the computer (Ctrl-Alt-Del).




0FFH = Command not complete.

Explanation:

     The command has not yet completed.

Recommended action:

     Wait for the command to complete.




------------------------------------------------------------------------



9.  THE REMOTE PROGRAM LOAD (RPL) FACILITY


     The Invisible LAN includes a Remote Program Load (RPL) facility.
The RPL facility lets you boot a computer directly off the network,
instead of from its local diskette drive.  The Invisible LAN's RPL
facility is compatible with the IBM PC Network's RPL facility.

     If the computer is unable to boot from its local diskette drive and
the computer has no fixed disk, it will send a boot request to a station
named IBMNETBOOT.  In order for the RPL to succeed, there must be a
station on the network named IBMNETBOOT which is prepared to handle
remote boot requests.

     The RPL facility is independent of the operating system.  The only
restriction is that the operating system must access the disk through
INT 13H and not try to use the diskette hardware directly.

     Note:  A computer which has a local fixed disk cannot be booted off
the network.  This rule applies regardless of whether or not the fixed
disk is bootable.

     Note:  The RPL facility is only present in ROM-resident versions of
NetBIOS.




9.1.  REMOTE PROGRAM LOAD PROCEDURE


     During self-test, the NetBIOS determines whether or not there is a
local fixed disk.  If there is no local fixed disk, the NetBIOS steals
the INT 19H Bootstrap interrupt vector.  As a result, when the ROM BIOS
tries to boot the disk by calling INT 19H, control passes to the RPL
facility.  The RPL facility then performs the following operations:

     1.  Try to boot the local diskette.  The RPL facility issues a
Diskette Reset command to INT 13H, followed by a Read Sector command to
read sector 1, head 0, cylinder 0, drive 0 into memory location 0:7C00H.
If the Read Sector command succeeds, the RPL facility completes the
bootstrap procedure by executing a FAR JMP to memory location 0:7C00H.

     2.  Issue a RESET command to NetBIOS through INT 5CH.

     3.  Issue a CALL command to NetBIOS in order to establish a session
with a remote station named IBMNETBOOT.  (The 16-character NCB_CALLNAME
field is set equal to the 10-character string "IBMNETBOOT" followed by 6
bytes of binary zeros.) The permanent node name is used as the local
name for the session.  If the CALL fails, the RPL facility restores the
top 1K of memory to the system (by incrementing the memory size variable
at 0:413H) and passes control to the original INT 19H handler.  If the
CALL succeeds, the RPL facility continues with the steps below.

     4.  Activate the disk redirector.  The disk redirector steals the
INT 13H Diskette interrupt vector, so that any calls to INT 13H will be
sent to the IBMNETBOOT station.

     5.  Attempt a simulated diskette boot.  The RPL facility issues a
Diskette Reset command to INT 13H, followed by a Read Sector command to
read sector 1, head 0, cylinder 0, drive 0 into memory location 0:7C00H.
(Of course, the disk redirector will send these calls to IBMNETBOOT).
If the Read Sector command succeeds, the RPL facility completes the
bootstrap procedure by executing a FAR JMP to memory location 0:7C00H.

     6.  If the simulated diskette boot fails, the RPL facility issues a
HANG UP command to close the session with IBMNETBOOT, and then passes
control to the original INT 19H handler.

     Compatibility note:  The IBM PC Network's RPL facility does not
intercept the INT 19H Bootstrap interrupt vector.  Instead, it
intercepts the INT 18H ROM BASIC interrupt vector, so that control will
pass to the RPL facility when the ROM BIOS tries to invoke ROM BASIC
following an unsuccessful diskette boot.  However, this scheme does not
work on non-IBM computers, because non-IBM computers do not have ROM
BASIC.  The Invisible LAN uses the INT 19H Bootstrap interrupt vector so
that RPL will work on both IBM and non-IBM computers.




9.2.  THE DISK REDIRECTOR


     The disk redirector intercepts all calls to the INT 13H Diskette
interrupt vector.  Each call is sent over the network to the IBMNETBOOT
station.  The IBMNETBOOT station executes the call and sends back the
results.  The disk redirector then passes the results to the caller of
INT 13H.

     The disk redirector can be turned off with the UNLINK command.
After UNLINK is issued, INT 13H calls will go to the local diskette
BIOS.  This makes it possible to access local diskette drives.




9.2.1.  READ SECTOR COMMANDS


     When a Read Sector command is issued to INT 13H, the disk
redirector sends an 11-byte message to IBMNETBOOT having the following
format:

(2 bytes)  AX register from call to INT 13H.
(2 bytes)  CX register from call to INT 13H.
(2 bytes)  DX register from call to INT 13H.
(2 bytes)  ES register from call to INT 13H.
(2 bytes)  BX register from call to INT 13H.
(1 byte)  Carry flag status from call to INT 13H:  00H=clear, 01H=set.


     IBMNETBOOT replies with a message of the following format:

(2 bytes)  Resulting AX register.
(2 bytes)  Resulting CX register.
(2 bytes)  Resulting DX register.
(2 bytes)  Resulting ES register.
(2 bytes)  Resulting BX register.
(1 byte)  Resulting Carry flag status:  00H=clear, 01H=set.
(xx bytes)  Data.  The length of the data is 512 bytes times the
            resulting AL register.


     When the disk redirector receives this reply, it places the
returned data into the user's buffer (specified by ES:BX), sets the CPU
registers and Carry flag to the resulting values, and then returns to
the caller of INT 13H.




9.2.2.  WRITE SECTOR COMMANDS


     When a Write Sector command is issued to INT 13H, the disk
redirector sends an 11-byte message to IBMNETBOOT having the following
format:

(2 bytes)  AX register from call to INT 13H.
(2 bytes)  CX register from call to INT 13H.
(2 bytes)  DX register from call to INT 13H.
(2 bytes)  ES register from call to INT 13H.
(2 bytes)  BX register from call to INT 13H.
(1 byte)  Carry flag status from call to INT 13H:  00H=clear, 01H=set.


     Following this 11-byte message, the disk redirector sends a second
message to IBMNETBOOT.  The second message has the following format:

(xx bytes)  Data.  The length of the data is 512 bytes times the AL
            register from the call to INT 13H.  The data is taken from
            the user buffer specified in ES:BX.


     IBMNETBOOT replies with a message of the following format:

(2 bytes)  Resulting AX register.
(2 bytes)  Resulting CX register.
(2 bytes)  Resulting DX register.
(2 bytes)  Resulting ES register.
(2 bytes)  Resulting BX register.
(1 byte)  Resulting Carry flag status:  00H=clear, 01H=set.


     When the disk redirector receives this reply, it sets the CPU
registers and Carry flag to the resulting values, and then returns to
the caller of INT 13H.




9.2.3.  OTHER DISK COMMANDS


     The disk redirector cannot process Format commands, Read Long
commands, or Write Long commands.  If one of these commands is issued to
INT 13H, the disk redirector immediately returns an "invalid command"
error to the caller of INT 13H.

     When any other command is issued to INT 13H, the disk redirector
sends an 11-byte message to IBMNETBOOT having the following format:

(2 bytes)  AX register from call to INT 13H.
(2 bytes)  CX register from call to INT 13H.
(2 bytes)  DX register from call to INT 13H.
(2 bytes)  ES register from call to INT 13H.
(2 bytes)  BX register from call to INT 13H.
(1 byte)  Carry flag status from call to INT 13H:  00H=clear, 01H=set.


     IBMNETBOOT replies with a message of the following format:

(2 bytes)  Resulting AX register.
(2 bytes)  Resulting CX register.
(2 bytes)  Resulting DX register.
(2 bytes)  Resulting ES register.
(2 bytes)  Resulting BX register.
(1 byte)  Resulting Carry flag status:  00H=clear, 01H=set.


     When the disk redirector receives this reply, it sets the CPU
registers and Carry flag to the resulting values, and then returns to
the caller of INT 13H.




------------------------------------------------------------------------




10.  NETBIOS PROGRAMMING HINTS


     Certain questions and problems seem to come up repeatedly in
writing programs that use NetBIOS.  The following sections should help
you avoid the common pitfalls.




10.1.  SESSIONS VERSUS DATAGRAMS


     Programmers often wonder if they should use sessions or datagrams
to move data.  The rule is simple:  Use datagrams when you need to
broadcast information to many stations simultaneously.  In all other
cases, use sessions.

     Although sessions may seem to involve more overhead than datagrams,
in fact the reverse is true.  Datagrams are always transmitted as
broadcasts, so sending a datagram consumes CPU time and buffer space on
every station in the network.  By contrast, session data is transmitted
directly and only to the intended destination station.

     Although using a session involves more programming steps than
sending a datagram, the session handles all acknowledgements and
retransmissions of data, as well as synchronizing the sending and
receiving stations.  If you use datagrams, you have to program all these
functions yourself.  You may think that you can do this more simply by
programming it yourself rather than by using a full-blown session, but
you can't.  The code in NetBIOS and TransBIOS is highly optimized code
written by an expert.  You should take advantage of the expertise that
is built in to NetBIOS.




10.2.  WAIT-POST INVERSION


     NetBIOS commands are carried out in two phases:  an initiation
phase and an execution phase.

     The initiation phase begins when you issue INT 5CH.  At the end of
the initiation phase, your program receives a WAIT notification, which
indicates that the command has been successfully initiated and will
execute at some later time.  If the high-order bit of NCB_COMMAND is
zero, the WAIT notification is a call to INT 15H with AX=9080H.  If the
high-order bit of NCB_COMMAND is one, the WAIT notification is the
return from INT 5CH.

     The execution phase begins after the end of the initiation phase.
At the end of the execution phase, your program receives a POST
notification, which indicates that the command is complete.  If the
high-order bit of NCB_COMMAND is zero, the POST notification is a call
to INT 15H with AX=9180H.  If the high-order bit of NCB_COMMAND is one,
the POST notification is a call to the NCB_POST procedure.

     Normally, one would expect the POST notification to occur after the
WAIT notification.  However, it is possible that the POST notification
may occur before the corresponding WAIT notification.  In other words:

     *  If the high bit of NCB_COMMAND is zero, the INT 15H with
        AX=9180 may occur before the INT 15H with AX=9080H.

     *  If the high bit of NCB_COMMAND is one, the call to NCB_POST may
        occur before the original INT 5CH returns.

     Your program must be prepared to deal with these possibilities.




10.3.  RECEIVE ORDERING AND POSTING


     When you issue RECEIVE-type commands, NetBIOS remembers the order
in which the commands were issued.  When data arrives, the RECEIVE-type
commands are filled in the same order they were originally issued;  the
first command issued is the first to receive data.

     NetBIOS attempts to post the RECEIVE-type commands (i.e., call
their NCB_POST routines) in the same order that the commands were filled
in.  However, this is not guaranteed.  In other words, do not assume
that RECEIVE-type commands will be posted in the same order that the
commands receive data.

     The order in which RECEIVE-type commands receive data is determined
by the order of the INT 5CH calls, not by the order of calls to
NCB_POST.




10.4.  USING CANCEL


     When you CANCEL a command, the command's NCB_POST routine is called
with a return code of 0BH.  The NCB_POST handler must be able to
recognize this return code and act accordingly.

     Do not assume that the command you are cancelling will already be
complete when the CANCEL returns.  In other words, after the CANCEL
command returns, you must wait until the canceled command has
NCB_CMD_CPLT not equal to 0FFH, or until the NCB_POST for the canceled
command is called.

     When your program terminates, it is very important that you CANCEL
all outstanding NCBs.  Otherwise, when the NCB completes, another
program's data or code will get overwritten, and a non-existent NCB_POST
routine may be called.




10.5.  THE MEANING OF LOCAL SESSION NUMBERS


     A local session number is just that -- local.  It is a number that
your program uses to communicate with your local NetBIOS, in order to
specify a particular session.

     There is no relationship whatsoever between the local session
number at one end of a session, and the local session number at the
other end of the session.




10.6.  THE MEANING OF NAME NUMBERS


     A name number is a number that your program uses to communicate
with your local NetBIOS, in order to specify a particular name.

     There is no relationship whatsoever between the name numbers used
on one station, and the name numbers used on any other station.

     You may wonder why name numbers exist at all -- couldn't you just
use the name itself instead of the name number?  The answer is, name
numbers exist because IBM designed NetBIOS that way.  It would have been
possible for IBM to design NetBIOS without having name numbers, but
that's not what they did.




10.7.  WHEN AN NCB CAN BE RE-USED


     Once you issue an INT 5CH, the NCB belongs to NetBIOS.  You may not
modify or re-use the NCB until the command is complete.

     You may wonder when it is legal to re-use the NCB.  You may re-use
the NCB after any of the following has occurred:

     *  The NCB_CMD_CPLT byte has changed to a value other than 0FFH.

     *  For commands issued with the high bit of NCB_COMMAND equal to
        zero, NetBIOS has executed INT 15H with AX=9180H.

     *  For commands issued with the high bit of NCB_COMMAND equal to
        zero, the INT 5CH has returned.

     *  For commands issued with the high bit of NCB_COMMAND equal to
        one, NetBIOS has called the NCB_POST routine.




10.8.  ISSUING INT 5CH WITHIN NCB_POST


     It is legal for your NCB_POST handler issue INT 5CH commands.  In
fact, this is a common programming practice.  However, you should be
careful about the following:

     *  Remember that NCB_POST can be called before INT 5CH returns.  If
        each NCB_POST does another INT 5CH call, you can overflow the
        available stack space.  Your program should take steps to
        minimize the use of stack space, or switch to a private stack.

     *  Any command issued within an NCB_POST should be issued in
        no-wait form (high bit of NCB_COMMAND equal to one).  Avoid
        having the NCB_POST routine wait for any other command to
        complete.




10.9.  PROGRAMMING A SERVER-CLIENT CONNECTION


     Many network applications are structured as a server and a client.
The server is generally designed to support several clients
simultaneously.  The conventional method for using NetBIOS to implement
a server-client relationship is for each client to have a session with
the server.

     Communication between the client and server proceeds as follows.
First, the client opens a connection with the server.  Then, the client
initiates a series of "transactions" with the server.  For each
transaction, the client sends a request to the server, and the server
responds by sending results back to the client.  Finally, when the
client no longer needs access to the server, the client closes the
conenction.

     The following sections describe the procedures that are
conventionally used to create such an application.




10.9.1.  OPENING CONNECTIONS


     When the server starts, it issues a LISTEN with NCB_CALLNAME
containing "*".  The server leaves this LISTEN outstanding all the time.

     The client issues a CALL with NCB_CALLNAME equal to the server's
name.  When the client's CALL completes successfully, it is connected to
the server.

     When the server's LISTEN completes successfully, it knows that a
new client has established a connection.  NCB_CALLNAME contains the name
of the client.  The server immediately issues a new LISTEN so it can
continue to accept additional client connections.  (The new LISTEN is
often issued in the NCB_POST routine of the original LISTEN.)




10.9.2.  TRANSACTIONS - CLIENT END


     A client begins a transaction by issuing a SEND to send a request
to the server.  The client and server must, of course, agree on the
format of the data to be sent.

     When the SEND completes, the client immediately issues a RECEIVE to
get the server's response.  This should be done in the SEND command's
NCB_POST, and normally the same NCB is used.  When the RECEIVE
completes, the transaction is complete.

     As a variation on the above technique, the client may issue a
RECEIVE before issuing the SEND, so as to ensure that the RECEIVE will
be outstanding before the server issues its SEND command to return the
results.  (Although a NetBIOS RECEIVE operates correctly regardless of
whether it is issued before or after the corresponding SEND, it is more
efficient if the RECEIVE is issued first.) Of course, you must use two
different NCBs if you do this.  In practice, this variation is rarely
beneficial unless the server computer is much faster than the client
computer.  By issuing the RECEIVE within the SEND command's NCB_POST,
the client will almost always have its RECEIVE outstanding before the
server can issue its SEND.




10.9.3.  TRANSACTIONS - SERVER END


     The server end of a transaction is opposite to the client's end --
the server first receives some data, and then sends a response.
Complications arise, however, because the server must manage several
NetBIOS sessions simultaneously, and it must be able to receive data
from any of them at any time.

     Several techniques exist for managing the server end of
transactions.  The techniques are described below:




10.9.3.1.  RECEIVE ANY METHOD


     The server can issue a RECEIVE ANY.  In this case, when data is
received from any client, the RECEIVE ANY command gets the data, and the
NCB_LSN field indicates which client sent the data.

     If the RECEIVE ANY return code is 06H ("message incomplete"), the
server can issue a RECEIVE to get the remaining data.  A common practice
is to specify a very small NCB_LENGTH in the RECEIVE ANY, so it only
receives the first few bytes of data.  The server looks at the first few
bytes of data to determine what type of transaction is being performed,
and then issues a RECEIVE to get the remaining data.  It is even legal
to issue RECEIVE ANY with NCB_LENGTH equal to zero, if the server only
needs to know which client is sending the request.

     After the RECEIVE ANY (or RECEIVE, if needed) completes, the server
performs the requested operation, and then issues a SEND to send the
results to the client.  When the SEND completes, the server issues a new
RECEIVE ANY.

     Generally, the first RECEIVE ANY is issued when the server starts.
With this technique, it is possible to run an entire server with just
two NCBs:  one for LISTEN commands, and another for RECEIVE ANY,
RECEIVE, and SEND commands.




10.9.3.2.  RECEIVE-PER-SESSION METHOD


     The server may keep a separate RECEIVE outstanding for each
session.  In this case, when a RECEIVE completes, the server performs
the requested operation and then issues a SEND to send the results to
the client.  When the SEND completes, the server issues a new RECEIVE.

     If a RECEIVE completes with return code 06H ("message incomplete"),
the server may issue another RECEIVE to get the remaining data.  In
situations where transaction requests are highly variable in size, a
common technique is to use a fairly small NCB_LENGTH in the initial
RECEIVE.  Small transaction requests can then be processed immediately
upon return from the initial RECEIVE.  Large transaction requests are
queued until a large buffer becomes available, at which point a second
RECEIVE is issued to get the remaining data into the large buffer.

     This technique requires one NCB for each network session.  The same
NCB is used for LISTEN, RECEIVE, and SEND.  When a LISTEN completes, a
new LISTEN is issued using a different NCB.  (It is not a good idea for
the server to maintain multiple LISTEN commands outstanding at the same
time, because this fills up the NetBIOS session table for no good
reason.)




10.9.3.3.  MULTIPLE RECEIVE ANY METHOD


     The server may keep multiple RECEIVE ANY commands outstanding.
Whenever a RECEIVE ANY completes, the NCB_LSN field indicates which
client sent the transaction request.  The server performs the requested
operation, then issues a SEND to send the results to the client.  When
the SEND completes, the server re-issues the RECEIVE ANY command.

     This method works well if transaction requests always fit in the
RECEIVE ANY data buffer.  However, it gets complicated if a transaction
request is too long to fit in the RECEIVE ANY data buffer.  In this
case, the RECEIVE ANY completes with return code 06H ("message
incomplete"), and the data is continued in the next RECEIVE ANY command.
Further complications are:  (1) if all RECEIVE ANY buffers are filled
before the data is exhausted, the server must issue additional RECEIVE
or RECEIVE ANY commands to get the remaining data;  (2) the server must
remember the order in which it issued the RECEIVE ANY commands, because
this is the order in which the commands are filled, and they may not be
posted in this order;  (3) if two clients send requests at the same
time, the server must deal with a situation where it has several RECEIVE
ANY commands for one client and several for another.

     This technique requires one NCB for LISTEN commands, plus one NCB
for each RECEIVE ANY.




10.9.4.  CLOSING CONNECTIONS


     When a client wants to close a connection with the server, the
client issues a HANG UP.

     When the client issues a HANG UP, the server gets back a RECEIVE or
RECEIVE ANY command with a return code of 0AH ("session closed").  This
indicates to the server that the client has closed the connection.




10.9.5.  ERROR HANDLING - CLIENT END


     When the client gets back any SEND or RECEIVE with a non-success
return code, the session has been closed or aborted.  If it wishes to
continue communication, the client must issue a new CALL to create a new
connection.

     If the return code is 0AH ("session closed"), it means that the
server issued a HANG UP command.  In this case, it is probably
desireable not to try to establish a new connection, because the server
probably decided that the client is misbehaving.




10.9.6.  ERROR HANDLING - SERVER END


     When a session is aborted, or when a client closes a session, the
server gets back a RECEIVE, RECEIVE ANY, or SEND command with a
non-success return code.  In any case, the session is terminated, and
the server should clean up any resources associated with the session.
NetBIOS guarantees that sessions never simply "disappear" without the
server getting notified.

     If the server decides that a client is misbehaving, it may
terminate the session by issuing a HANG UP.  When the HANG UP completes,
the session is terminated, and the server can clean up.
