
Click above to get retro games delivered to your door ever month!
X-Hacker.org- CA-Clipper Tools . Book 4-Appendices - <b>nbscall()</b>
[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
NBSCALL()
Opens a NetBIOS session sending and receiving buffer and attempts a
connection setup
------------------------------------------------------------------------------
Syntax
NBSCALL(<cSourceName>,[<nRecBuffer>],[<nSendBuffer>],
<cTargetName>,[<nPacket>],[<nRecTimeout>],
[<nSendTimeout>]) --> nHandle
Netware: 2.2 and 3.11
Arguments
<cSourceName> Designates the NetBIOS name of the communication's
transmitting side.
<nRecBuffer> Designates the selected size of the receiving buffer.
If no value is passed for <nRecBuffer>, no receiving buffer is
established. The minimum size of the receiving buffer is <nPacket>. If
the value for <nRecBuffer> is too small, it is changed automatically by
NBSCALL(). The maximum size of the receiving buffer is 64 KByte.
<nSendBuffer> Designates the selected size of the sending buffer.
If no value is passed for <nSendBuffer>, no sending buffer is
established. The minimum size of the sending buffer is <nPacket>. If
the value for <nSendBuffer> is too small, it is changed automatically by
NBSCALL(). The maximum size of the sending buffer is 64 KByte.
<cTargetName> Designates a NetBIOS name that specifies the target
station.
<nPacket> Designates the packet size of the data that is sent in
bytes. The default value is 512 Bytes.
<nRecTimeout> Designates the timeout for the following receiving
operations in 1/2 seconds. The default value (0) designates no timeout.
<nSendTimeout> Designates the timeout for the following sending
operations in 1/2 seconds. The default value (0) designates no timeout.
Returns
If an operation is successful, NBSCALL() returns a communication handle.
The return value contains a numeric value that is greater than 0. You
should store the handle in a variable because all further operations
that refer to an established buffer require a communication handle. If
an error occurs, the function returns 0.
Description
NBSCALL() allows you to establish a communication buffer for a NetBIOS
session communication with other workstations in the network. The
communication buffer can contain the sending and receiving buffer
through which the interrupt controlled sending and receiving of data is
processed.
<nSourceName> is the NetBIOS name of the process that transmits the data
(see the Introduction to this chapter). The name can be added to the
local name table with the functions NBADDNAME() or NBADDGROUP() before
the call of NBSCALL(). If <nSourceName> has not been added to the name
table, it is added by NBSCALL() automatically.
The parameters <nRecBuffer> and <nSendBuffer> determine the size of
receiving and sending buffers. The buffers are automatically designed
for one NetBIOS packet. Each buffer can be up to 64 KByte. However,
the size of the buffer that is allocated by NBSCALL() depends on the
application and the configuration of the computer used.
The parameter <cTargetName> is mandatory. The session is set up with
the station specified by <cTargetName>.
<nPacket> determines the maximum size of the data range of the NetBIOS
packets that are sent or received. The maximum value (and the default
value) is 512 bytes. Smaller packets can be sent without failure.
However, larger packets are discarded. The value of <nPacket> is also
valid for use in sending data.
The seconds for the timeout are not determined individually for each
sending and receiving operation. The timeout is set when the session is
opened by passing the parameters <nRecTimeout> and <nSendTimeout>. The
parameters can contain numeric values that specify the timeout in steps
of 1/2 second.
If all parameters have been passed correctly and the buffers have been
established successfully, NBSCALL() attempts to set up a session between
the current workstation and the target station. However, the target
station must expect the connection setup. If a CA-Clipper application
is running on the target station, the function NBSLISTCON() must have
been called. If no acknowledgment is returned by the target station
within the specified timeout, NBSCALL() releases the reserved buffers
and returns 0.
After a successful connection setup NBSCALL() returns a communication
handle that is greater than 0. If a value has been passed for
<nRecBuffer>, NBSCALL() initiates an interrupt controlled receiving
mechanism that receives incoming packets in the background and then
copies them to a receiving buffer. The data can then be read with the
PPCREAD() function within a CA-Clipper application. If the receiving
buffer is full, incoming data is discarded without notifying the sender.
Data should be removed from the receiving buffer and processed as soon
as possible. You should either read the contents of the buffer
periodically (polling) or supervise the buffer on an event-oriented
basis: for example, with the function PPCKEY().
Note
. Unlike a NetBIOS datagram communication, a NetBIOS session
communication is connection-oriented. A connection is established
between two stations. As long as no error occurs, a successful
delivery of sent packets is guaranteed.
Examples
. Attempt to set up a NetBIOS session connection to workstation
MIKE. If the setup is successful, a 5000 byte receiving buffer and a
1000 byte sending buffer are established. The source name on the
local workstation is KEITH:
nHandle=NBSCALL("MICK",5000,1000,"MIKE")
IF nHandle=0
? 'Failure!'
ENDIF
. The destination side can wait for the connection with the
following call:
nHandle:=NBSLISTCON("MIKE",2000,2000)
See Also: NBSLISTCON() PPCCANCEL() PPCKEY() PPCREAD() PPCWRITE()
Online resources provided by: http://www.X-Hacker.org --- NG 2 HTML conversion by Dave Pearson