Converted to HTML by J.J. Proveniers
CBIS,Inc.
5875 Peachtree Industrial Blvd.
Bldg. 100 Suite 170
Norcross, GA 30092
Net BIOS is a software interface between computer programs and a Local Area Network Adapter (LANA), or "LAN card". It is used in Local Area Network (LAN) systems consisting of IBM compatible microcomputers. The components of a LAN are the computers, each containing a LAN card, the interconnect cables, and the Net BIOS software. Net BIOS has been implemented for a variety of LAN card types. These include Token Ring, Ethernet and ARCNET. Application programs on different computers can communicate by using Net BIOS services to send and receive messages.
The purpose of the Net BIOS is to isolate the application program from the actual type of hardware used in the LAN. It also spares the application programmer the details of network error recovery and low level message addressing or routing.
In a Net BIOS implementation of a LAN, the computers on the system are known by names. Each computer has a permanent name that is programmed onto the LAN card. Computers on the system can also be known by names designated by the programmer. The commands available in Net BIOS include commands to add and delete names.
Computers on a Net BIOS implementation of a LAN can communicate either by establishing a session or by using datagram or broadcast methods. Sessions allow a larger message to be sent and handle error detection and recovery but they only allow computers to communicate on a one-to-one basis. Datagram and broadcast methods allow one computer to communicate with several other computers at the same time, but are limited in message size. Datagram and broadcast methods of communication do not handle error detection and recovery. Net BIOS session control commands and session data transfer commands allow communication through sessions. Net BIOS datagram commands allow communication without the use of sessions.
All commands are presented to the Net BIOS in a format called Network Control Blocks (NCB). These blocks are allocated in memory by the user program. The user program is also responsible for setting the neccessary input fields of the NCB and initializing the fields not used to zeros. Several fields in the NCB are reserved for output from Net BIOS upon completion of a command.
This manual discusses names and data communication methods in a Net BIOS implementation of a LAN. Discussions of NCBs and Net BIOS commands include descriptions of all the fields in an NCB and all Net BIOS commands. Each Net BIOS command description lists the NCB fields that are used for input or output for that command. NCB and command information is summarized in the appendices at the end of this document.
Chapter 1 gives a general overview of Net BIOS concepts. It defines and states the purpose of Net BIOS. Computers in a Net BIOS implementation are known on a Local Area Network by names. This section explains the concepts concerning names. Computers on a network communicate by session or by datagram methods. The advantages of each of these methods of communication are discussed. This chapter includes a list of the steps that must be taken in order for two computers to communicate through a session. Use of Net BIOS through the Network Control Block format and the concept of wait and no-wait command modes is introduced.
Chapter 2 gives more detailed information about wait and no wait command modes and lists the general steps necessary to pass a Net BIOS command from a user program to Net BIOS for execution.
Chapter 3 lists and describes the 14 fields in a Network Control Block. This chapter includes an example of an assembly language NCB structure.
Chapter 4 describes each of the available Net BIOS commands in detail and lists the Network Control Blocks that are used for each command. Each command description specifies which fields must be set by the user program and which fields are returned by Net BIOS after execution of the command.
Finally, Appendices A and B include tabular summaries of the information presented in the text concerning Net BIOS commands and Network Control Blocks.
Appendix C contains a listing of the error codes that may be encountered while using the Net BIOS.
The purpose of the Net BIOS is to isolate the application program from the actual type of hardware used in the LAN. It also spares the application programmer the details of network error recovery and low level message addressing or routing.
Net Bios Names
Each computer on the network is known and addressed by the other computers on the network by a name. Each computer has a permanent name and can be given additional names by the user during network communication. Names are 16 characters long and should not contain the asterisk (*) character.
The permanent name is called the node number. The node number is usually in ROM (read only memory) on the LAN adapter card or is set by dip switches on the LAN adapter card. The node number consists of 10 characters of binary zeros followed by 6 more characters which must be unique on the network.
Up to 16 local names may be added to the Net Bios for each computer on the network by the use of the ADD NAME and ADD GROUP NAME commands. These names are stored in a local name table and are lost when the computer is turned off, or when the Net BIOS RESET command is issued. A local name can be removed from the local name table by use of the Net BIOS DELETE NAME command.
The local names may be unique names or group names. A unique name is guaranteed by the Net BIOS to be unique across the LAN. A group name added at one computer may also be added, as a group name, at other computers.
Data transfer commands must specify both a source and a destination name. Since multiple names are allowed on each computer, several unrelated tasks may use the Net BIOS without interference.
Types of data transfer
Data can be transferred from computer to computer by using session level or datagram level commands of the Net BIOS.
Session level commands allow user programs to communicate without requiring that they handle the details of network error detection or breaking larger messages into smaller messages to match any physical network limitations. Session level commands are restricted to communication from one unique name to another. Before using session level data transfer, the applications must negotiate a "logical connection". This is accomplished by issuing a Net BIOS CALL command on one computer and a Net BIOS LISTEN command on another computer.
Datagram level data transfers are addressed to a lower level in the LAN adapter card. The intialization requirements for sending or receiving a datagram message are simpler, however, more of the error control and data formatting problems are left to the user program. Datagrams are also restricted in the size of messages to 512 bytes or less. Datagrams are useful for performing functions not possible at the session level. For example, a datagram message can be "broadcast" to more than one computer on the network at the same time.
Data Transfer Example
A session level data transfer sequence can be grouped into four steps. Each step on one computer in the network must have a complementary step performed on another computer in the network.
After creating an NCB, it is passed to the Net BIOS by loading the address (segment:offset) of the NCB into the ES:BX registers, and then executing a software Interrupt 5C hex. The Net BIOS will perform the operation specified by the command code field in the NCB.
Net Bios Command Modes
Three command modes are available when executing a Net BIOS command:
| High-Order Bit | Post Field | Mode |
|---|---|---|
| 0 | don't care | Wait |
| 1 | 0:0 | No-wait polling |
| 1 | address of post routine | No-wait with post |
Wait Mode
When a wait mode command is issued, the Net BIOS will not return control to the user program until the command has been completed. Upon return, the AL register will contain 0 if no error occurred or an error code value. The AH register contents are destroyed, but other registers are not changed. The error code in AL is the same as that contained in the NCB RETCODE field.
No-Wait Polling Mode
The Net Bios will, after minimum processing, return immediately, even though the command may not have completed. On return, the AL register will contain an immediate error code or 0.
| Contents AL | Indicates |
|---|---|
| not 0 | Command could not be queued (e.g., invalid COMMAND code). |
| 0 | Command was queued |
If the command was queued successfully then the program should poll the CMD_DONE field of the NCB, until CMD_DONE field is not 0ffh. This indicates that the command has completed and all other NCB fields are valid. The AH register contents are destroyed, but other registers are not changed.
No-Wait With Post Mode
The Net Bios will return immediately, even though the command may not have completed. On return, the AL register will contain an immediate error code or 0.
| Contents AL | Indicates |
|---|---|
| not 0 | Command could not be queued (e.g., invalid COMMAND code). |
| 0 | Command was queued |
If the command could not be queued, the POST routine will not be called. The AH register contents are destroyed, and other registers are not changed.
If the command was queued, then when the command completes, the Net BIOS will call the user's POST routine with interrupts disabled, the stack set for an IRET, and ES:BX containing the address of the completed NCB.
Another Net BIOS command can be issued from the POST routine, however, it should also be a no-wait mode command.
The user POST routine should be as short as possible and no registers should be changed. Interrupts may be enabled in the POST routine.
In some cases, the user's POST routine will be called before control is returned from the INT 5Ch that started the command.
| FIELD | DESCRIPTION | |
|---|---|---|
| COMMAND | A 1 byte field used for the Net Bios command code. The high order bit of this field should be set to 1 to indicate no-wait mode or 0 to indicate wait mode. The remaining 7 bits are used for the command code. All Net BIOS commands except RESET and CANCEL have wait and no-wait options. In no-wait mode the POST field must also be set. In wait mode the Net BIOS waits for the command to complete before returning to the calling program. In the no-wait mode the Net BIOS queues the command for later execution and then returns to the calling program, which may perform other processing or issue additional Net BIOS commands. | |
| RETCODE | A 1 byte field in which Net BIOS command results are returned. This field will contain a zero if no error or an error code if an error was encountered. The error codes are listed in Appendix C. | |
| LSN | A 1 byte field containing the local session number that is assigned by Net BIOS when a session is established. This number will have a value between 1 and 254. This field is returned by CALL and LISTEN, and must be supplied for SEND and RECEIVE commands. | |
| NUM | A 1 byte field used for the name number associated with the name in the local name table. This number is returned by ADD NAME commands and must be supplied for RECEIVE ANY and datagram commands. The value of this number ranges from 1 to 254. | |
| BUFADR | A 4 byte field used for the address of message to be sent or received. | |
| BUFLEN | A 2 byte field containing the length in bytes of message buffer. For receive commands, this field is set to the maximum buffer size and the actual length is returned in this field upon completion of the Net BIOS command. | |
| CALLNAME | A 16 byte field used to indicate the name of the computer you want to communicate with for CALL, LISTEN and datagrams. For a CHAIN SEND command, the first word specifies the length of the second buffer, and the next two words specify the address. All 16 bytes must be used. | |
| NAME | A 16 byte field used to specify a local name. Specifies a name to add to the local name table for ADD NAME, or the name to use for other commands. | |
| RTO | A 1 byte field used for receive time-out specifications in .5 second increments. Must be set for CALL and LISTEN commands. This field indicates the maximum time that will be allowed before an error condition will result on a receive command. Once the session is established this value remains constant throughout the session. | |
| STO | A 1 byte field used for send time-out specifications in .5 second increments. This field must be set for CALL and LISTEN commands. If the time expires before the send has completed a time out error will result and the session will be terminated. | |
| POST | Address of user interrupt routine called when command completes and no-wait mode mode was specified in command code. Not called if set to 0:0. | |
| LANA_NUM | A 1 byte field that contains the number of the adapter card to be addressed by the command. It there are two adapter cards installed on the same computer then a 0 in this field signifies that the command is addressing the first card and a 1 indicates that the command is addressing the second card. If there is only one adapter card in the computer then this field should contain a 0. | |
| CMD_DONE | A 1 byte field that is set by Net BIOS when a command is completed. A value of 0FFH indicates the command has not completed. When the command has completed, CMD_DONE is set to same value as RETCODE. | |
| RES | A 14 byte field used internally by Net Bios. Should not be used for any other purposes. |
Assembly Language NCB Structure
Shown below is an example of an NCB defined in an assembly language program.
Session Control commands are used to initiate or terminate communication between two computers on the network, or to access the status information on a particular session.
Session Data Transfer commands are used to send or receive messages between computers once the session has been established.
Datagram commands are used to send and receive messages at a lower level in the LAN system. These messages are restricted in size but can be sent to and received from more than one computer at a time.
The commands available in each group are described below. For each command, the required NCB fields are listed. Although not absolutely required, it is good practice to initialize unused fields to zero in new NCBs. It is generally not necessary to clear unused fields when re-using an NCB for another command. For example, a completed LISTEN command returns the name of the caller in the CALLNAME field. It is not necessary to clear this field before using the same NCB for a RECEIVE command.
General Commands
The general commands are
These commands can be used to reset Net BIOS and specify the number of sessions and NCBs to be supported, to cancel previous commands, to determine the status of the Net BIOS, or to unlink from diskless boot.
Reset Command
Use this command to clear and configure the Net Bios.
Caution: When this command is issued, all existing names and sessions are lost, therefore it should be issued before starting any processes that use the Net Bios.
Caution: In some implementations, session and command buffers take space otherwise used for packet buffers. Therefore, keep these parameters reasonable.
Use this command to cancel a previous command.
Caution: If this command is used with a SEND or CHAIN SEND command the session will be terminated.
The following commands cannot be canceled:
Use this command to get the status of a Net Bios -- either local or remote.
The format of the Adapter Status Result buffer is shown in Table 1. The actual size of the status buffer will be 60 + 18n, where n is the number of names in the name table of the selected Net Bios (the permanent node name is not counted).
| Offset (Hex) | Bytes (Dec) | Field Description |
|---|---|---|
| 0 | 6 | Permanent node name. This six byte identifier is obtained from either a ROM on the LAN card or from the node address DIP switch. |
| 6 | 1 | External jumper status. The high bit of this byte indicates the interrupt number used by the LAN card -- 0 for IRQ 2 and 1 for IRQ 3. The second highest bit indicates the DMA chan- nel used by the LAN card -- 0 for channel 1 and 1 for channel 3. This byte is not sup- ported in all implementations. |
| 7 | 1 | Power on test result. Always zero in current versions. |
| 8 | 2 | Software version. First byte is the major version, second is the minor version number. |
| 0A | 2 | Minutes since system started. When this field reaches 0FFFFH, it rolls over to 0. |
| 0C | 2 | Number of CRC errors on received packets. (1) |
| 0E | 2 | Number of alignment errors. (1) |
| 10 | 2 | Number of transmit collisions. (1) |
| 12 | 2 | Number of aborted transmits. (1) |
| 14 | 4 | Number of packets transmitted. When this field reaches 0FFFFFFFFH, it rolls over to 0. |
| 18 | 4 | Number of packets received. When this field reaches 0FFFFFFFFH, it rolls over to 0. |
| 1C | 2 | Number of retransmits. (1) |
| 1E | 2 | Number of times receiver was out of buffers. (1) |
| 20 | 8 | Not used -- reserved. |
| 28 | 2 | Number of free network command blocks (NCBs). (2) |
| 2A | 2 | Number of NCBs specified in last RESET command. |
| 2C | 2 | Maximum possible number of NCBs that can be specified in RESET command. |
| 2E | 4 | Not used -- reserved. |
| 32 | 2 | Number of pending or active sessions. |
| 34 | 2 | Number of possible sessions specified in last RESET command. |
| 36 | 2 | Maximum number of possible sessions that can be specified in RESET command. |
| 38 | 2 | Maximum packet size supported on the network. Note, this is not related to the maximum session message size, which is 64K bytes. |
| 3A | 2 | Number of names in name table. |
| 3C | 18 | First name in name table. (3) * 16 bytes - name * 1 byte - name number (2 to 254) * 1 byte - name status. Bit patterns are: * G----000 - name add in progress * G----100 - active name * G----101 - delete pending * G----110 - improper duplicate name * G----111 - duplicate name, delete pending |
| 4E | X18 | Addition name table entries as needed. |
Unlink Command
Use this command to cancel diskless boot redirection. Typically, a diskless boot ROM makes a connection with a process that supplies a virtual floppy image and redirects INT 13 requests for drive A to this network device. This command cancels that redirection so that the local drive A may be accessed.
Caution: Once this command is issued, there is no way to re-establish the diskless boot connection.
Name commands allow the addition and deletion of local and group names for a computer on the network. The name commands are:
Following is a description of the name commands and the NCB fields that are used for these commands.
Add Name Command
Use this command to add a name to the Net Bios local name table. The name must be unique across the network.
Use this command to add a non-unique name to the Net Bios local name table. It the name already exists as a unique name by any other process or machine an error code will be returned in the RETCODE field and the name will not be added to the local name table.
Group names provide a mechanism to "broadcast" messages to a specific group of computers on the system. SEND DATAGRAM to a group name will be received by all computers that have issued a RECEIVE DATAGRAM under the group name.
Use this command to delete a name from the Net Bios local name table. If no sessions are active under the name to be deleted, the name will be deleted. If any sessions are active, then the command will not complete until these sessions are terminated.
Caution: Any of the following commands outstanding and associated with the deleted command will be terminated with RETCODE = 17h (name was deleted):
Session control commands are used to initiate or terminate communication between two computers on the network, or to access the status information on a particular session.
Session control commands are:
Call Command
This command is used to establish a session with another machine or process.
A LISTEN command must be outstanding for the called (remote) name. The session number is used when sending or receiving session data, or in the HANG UP (session terminate) command.
Use this command to wait for a session to be established. The session will be established when another machine or process executes a CALL to the name associated with the LISTEN command.
More than one session can be established under the same name, or same pair of names.
PRIORITY: Regardless of order in which the LISTENs are issued, a CALL received from a specific name when there is a LISTEN pending with a matching CALLNAME will take precedence over a LISTEN for any name (* in first character) command.
Use this command to close or terminate a session. It may be issued by either the CALLer or LISTENer.
If any RECEIVE commands for the session are outstanding on the machine issuing the HANG UP, they are completed with RETCODE = 0Ah (session closed).
If SEND commands are outstanding, the HANG UP completion will be delayed until the SEND has completed.
If the remote end has any RECEIVE or SEND commands in progress when HANG UP is started, they will be terminated with RETCODE = 0Ah.
If no remote RECEIVEs or SENDs are terminated with session closed, and if RECEIVE ANY commands are outstanding at the remote, one and only one of the RECEIVE ANYs will be terminated with the session closed error.
If no commands are outstanding at the remote machine when the HANG UP occurs, then the next session command issued by the remote will be terminated RETCODE set to either 08h (invalid session) or 0Ah (session closed).
Use this command to obtain the status of all sessions associated with a given name. Table 2 on the following page shows the format of the status.
Session Data Transfer commands are used to send or receive messages between computers once the session has been established.
Session data transfer commands are:
The commands available in this group are described below. For each command, the required NCB fields are listed. Send Command Use this command to send data to the machine or process with which a session as been established. The remote session must have issued (or issue before the time-out specified earlier in STO) a RECEIVE or RECEIVE ANY command.
Priority: SENDs are performed in the order in which they are issued.
Caution: If an error occurs on the send, then the session is terminated.
The CHAIN SEND command is similar to the SEND command, except the data to be transferred is contained in two separate buffers. CHAIN send concatenates these buffers -- the receiving end will see one message.
Use this command to receive data from a computer or process with which a session as been established. The remote session must issue a SEND or CHAIN SEND command.
If a send is not issued by the remote within the time specified earlier in RTO, the RECEIVE will complete with a time out error (RETCODE = 05h). Time outs do not cause session termination.
PRIORITY: RECEIVE commands are completed in the order in which they are issued. If received data could be used to complete either a RECEIVE or RECEIVE ANY, the RECEIVE is given priority and completed.
If the maximum buffer length was smaller than the length of the data, then the buffer is filled to the maximum and RETCODE = 06h is returned. The next RECEIVE (or RECEIVE ANY) will be completed with the remainder of the data.
Use this command to receive data from any session. The remote session must issue a SEND or CHAIN SEND command. There is no time-out on this command.
PRIORITY: RECEIVE ANY commands are completed in the order in which they are issued. If received data could be used to complete either a RECEIVE or RECEIVE ANY, the RECEIVE is given priority and completed.
If the maximum buffer length was smaller than the length of the data, then the buffer is filled to the maximum and RETCODE = 06h is returned. The next RECEIVE ANY (or RECEIVE) will be completed with the remainder of the data.
RECEIVE ANY is used by a process that services multiple users. Session termination by the local or remote process will cause the next pending RECEIVE ANY to complete with RETCODE = 0Ah (session terminated) or 18h (session terminated abnormally).
Datagrams provide a means to transfer data between processes without using the session mechanism. Messages may be sent to a given name, a group name, or to all processes. Datagram messages do not provide the same reliability as session data transfer, since the sender will not be notified when messages are undeliverable.
Datagram commands are:
Send Datagram Command
Use this command to send a datagram message. The Net Bios does not detect whether the message was successfully delivered.
Use this command to wait for a SEND DATAGRAM to the name associated with the NUM field. There is no time-out on this command. If the maximum buffer length was smaller than the length of the data, then the buffer is filled to the maximum and RETCODE = 06h is returned. The remaining data is lost.
Use this command to send a broadcast message. The Net Bios does not detect whether the message was successfully delivered.
Each SEND BROADCAST satisfies all outstanding RECEIVE BROADCAST commands on the network.
Use this command to wait for a SEND BROADCAST message. There is no time-out on this command.
Each SEND BROADCAST satisfies all outstanding RECEIVE BROADCAST commands on the network.
If the maximum buffer length was smaller than the length of the data, then the buffer is filled to the maximum and RETCODE = 06h is returned. The remaining data is lost.