Click above to get retro games delivered to your door ever month!

 SPXESTBCON()
 Opens the SPX sending and receiving buffer and tries a connection setup
------------------------------------------------------------------------------
 Syntax

     SPXESTBCON(<nSourceSocket>,[<nRecBuffer>],
        [<nSendBuffer>],<cTargetAddr>,[<nTargetSocket>],
        [<nPacket>],[<lHeader>],[<nRepeat>],[<lWatchDog>],
        [<nECBs>]) --> nHandle

     Netware: 2.2 and 3.11

 Arguments

     <nSourceSocket>  Designates the socket number 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
     SPXESTBCON().  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
     SPXESTBCON().  The maximum size of the sending buffer is 64 KByte.

     <cTargetAddr>  Designates the destination's internet address.  The
     target address is a 20-character string that represents a 10-character
     byte sequence.  The leading eight characters of <cTargetAddr> contain
     the network number of the target station.  The remaining 12 characters
     specify the station ID of the target station (node address).

     <nTargetSocket>  Designates the socket number of the communication's
     remote side.  The default value is <nSourceSocket>.

     <nPacket>  Designates the packet size of the data that is sent.  The
     packet size can be between 1 and 534 bytes.  Values outside of this
     range are changed automatically.  The default value is 534 Bytes.

     <lHeader>  Designates whether the data range and the header of the
     packet (.T.) or the data range alone (.F.) are transmitted to the
     receiving buffer.

     <nRepeat>  Designates the number of repeat attempts if a faulty
     packet transmission occurs.  The value is valid for all sending
     operations processed during a session.  A value of 0 indicates that SPX
     assumes the standard repeat value.

     <lWatchDog>  Designates whether the watchdog is activated (.T.) or
     not (.F.).  This parameter allows the supervision of the connection with
     watchdog, an SPX internal mechanism.  If the supervision is activated,
     watchdog checks in regular intervals to see if the remote station is
     still responding.  The default value (.T.) activates the watchdog.

     <nECBs>  Designates the number of ECBs (Event Control Blocks) that
     are added to the listening pool for the current connection.  The default
     value is 2.  With a higher value, the performance can be improved (for
     example, when working with slow computers).

 Returns

     If an operation is successful, SPXESTBCON() 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

     SPXESTCON() allows you to establish a communication buffer for an SPX
     communication with another station in the network.  SPXESTCON() also
     tries to set up an SPX connection (session) to this station.  The
     communication buffer can contain a sending and receiving buffer through
     which the interrupt controlled sending and receiving of data is
     processed.

     <nSourceSocket> is the socket number of the communication's transmitting
     side (see the Introduction to this chapter).  The socket can be opened
     with the function OPENSOCK() before the call of SPXESTBCON().  If
     <nSourceSocket> has not been opened, it is opened by SPXESTBCON()
     automatically.  If 0 is passed for <nSourceSocket>, SPXESTBCON() opens
     any available socket.

     The parameters <nRecBuffer> and <nSendBuffer> determine the size of the
     receiving and sending buffers.  The buffers are automatically designed
     for one NetBIOS packet.  Each buffer can be up to 64 KByte in size.
     However, the size of the buffer that is allocated by SPXESTBCON()
     depends on the application and the configuration of the computer used.

     The remote partner is specified by <cTargetAddr>.  The target address
     must be passed as a 20-character string (for example,
     "4921750400001B025A99").  Two bytes each represent one byte in
     hexadecimal form.  For an SPX communication, the target address must be
     unique.  It is not allowed to pass a broadcast address
     ("FFFFFFFFFFFFFFFFFFFF").  Application specific mechanisms are required
     to determine the stations waiting for a connection (for example, the
     storage of the net addresses of the waiting stations in a database or in
     the bindery).  If the current workstation is logged into a Netware
     server, the network address of a logged in remote station can be
     determined with the function NNETADR() by passing the user name.  Under
     Netware Lite, the leading eight characters of <cTargetAddr> (network
     number) must be passed with 0.

     <nTargetSocket> is the destination's internet address.  The default
     value is <nSourceSocket>.

     <nPacket> determines the maximum size of the data range of the SPX
     packets that are sent or received.  The maximum value (and the default
     value) is 536 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.

     With <lHeader> you can determine if the header of an SPX packet (42
     bytes) is transmitted to the receiving buffer.  The header can contain
     important information about the received packet.  For a description
     about the header structure, see the Introduction to this chapter.

     The number of repeat attempts for faulty sending operations during the
     session can be specified with <nRepeat>.  A value of 0 sets an SPX
     internal standard value.

     A session is supervised by an SPX watchdog.  If the watchdog determines
     that the remote station is not responding, a key trap can be triggered
     (see PPCKEY()).  The connection flag for the session is set to .F..  If
     you want to deactivate the watchdog, the parameter <lWatchdog> can be
     designated .F..

     SPX needs Event Control Blocks (ECBs) for receiving data and for
     administration purposes.  The ECBs are created and managed by
     SPXESTBCON() automatically.  The default value is two ECBs for each SPX
     session.  The value can be increased if slow computers are used.
     However, you cannot prevent data loss that is the result of a full
     receiving buffer.

     If all parameters have been set correctly and the buffers have been
     established successfully, SPXESTBCON() tries 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 SPXLISTCON() must have
     been called.  If no acknowledgment is returned by the target station
     within a specified timeout (about 30 seconds), SPXESTBCON() releases the
     reserved buffer and returns 0.

     After a successful connection setup, SPXESTBCON() returns a
     communication handle that is greater than 0.  If a value has been passed
     for <nRecBuffer>, SPXESTBCON() 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 an IPX communication, an SPX 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 an SPX connection to the target address
        "4921750400001B025A99".  If the connection can be set up, establish a
        5000 byte receiving buffer and a 1000 byte sending buffer.  The
        source and destination socket number is 20000:

        nHandle=SPXESTBCON(20000,5000,1000,"4921750400001B025A99")
        IF nHandle=0
           ? 'Error during connection setup!'
        ENDIF

     .  The remote station can wait for the connection with the
        following call:

        nHandle:=SPXLISTCON(20000,2000,2000)