TCP_Listen

version 6.8.1 (Modified)

TCP_Listen (remoteHost; localPort; remotePort; timeout; tcp_ID) Integer

The TCP_Listen command waits for a connection to be made from the machine referenced by remoteHost on the port referenced by remotePort. This command does not return control back to the 4th Dimension calling method until either a connection is made or the timeout period has elapsed. Though it may seem as though this would lock up your database until a connection was made, the command is friendly to other 4th Dimension processes that may be running. This command will slice time to other 4D processes you may already have running.

Most developers will want to issue this call from a method which has been spawned into its own 4D process (especially if you specify the timeout period to wait forever).

remoteHost is the host name or IP address of the machine that you are waiting for a connection from.

- If a null string is passed in this parameter, this command will accept an incoming connection from any machine.

- If a variable containing a null string is passed in this parameter, it will return the IP address of the connected machine.

Note: Under Windows, remoteHost will not accept an IP address from a distant machine; if this occurs, error –10049 "Specified address is not available from the local machine" will be generated. As a consequence, if you need to filter an IP address, it is better to use a variable containing a null string.

localPort contains the port on your local machine you wish to use for communication. If you pass a zero as this parameter, the command will find any unused port and pass that number back to this parameter.

remotePort identifies the port number to be listening for an incoming connection.

Note: After a call to TCP_Listen (or TCP_Open), remotePort may contain a negative value if the value passed to this parameter is above 32767. This will not disturb the connection.

As a workaround, you can use an intermediate variable:

   $v_ RemotePort:=v_ RemotePort
   $err:=TCP_Listen (v_ RemoteHostIPAdr;0;$v_ RemotePort;30;v_ SessionID)  

timeout specifies the number of seconds this command will wait for an incoming connection. A zero in this parameter will cause the command to wait indefinitely for an incoming connection. Caution should be taken when passing a zero since control will never be returned to the calling 4D process if a connection is never made. Never pass zero to this parameter in a single-process database.

tcp_ID is the long integer reference to the session that was opened. This reference will be used in all subsequent TCP external calls that reference this session.

Any TCP connection opened using the TCP_Listen command must be closed later using the TCP_Close command.

   C_LONGINT(vTCPID)
   C_INTEGER(vStatus)
   $err:=TCP_Listen ("";0;49152;30;vTCPID)
   $err:=TCP_State (vTCPID;vStatus)
   If (vStatus=8)     `connection was established
      DoSomething
      $err:=TCP_Close (vTCPID)
   End if 

Appendix B, TCP Port Numbers, TCP_Open, TCP_State.