Port Manager

The VTScada Port Manager service provides a simplified means for drivers to access and share Serial, TCP/IP, and UDP/IP ports. The service allows for a driver to make a single call before accessing a port for read and write operations. This call can provide all of the following:

  • Queued semaphore access to the port
  • Open the port connection to the remote device
  • Provide indication of success when ready to use
  • Provide indication of failure if the connection was not made
  • Provide an indication of failure if the port was disconnected during use

The port manager will return one of several error codes when a fault is detected, starting at a value of 1. A successful connection is indicated by a value of 0. While waiting for the connection attempt, the function will return nothing.

Error codes

Drivers making use of the PortManager should allocate a space of 50 errors to allow for the full range that can be provided by the service. Currently defined error codes are:

#PMNoError = 0

#PMPortNotDefined = 1

#PMPortFailToConnect = 2

#PMPortLostConnection = 3

#PMPortOutofRange = 4

#PMPortInUse_NotAvail = 5

#PMPortAccessDenied = 6

#PMPortGeneralFailure = 7

#PMPortParameterBad = 8

#PMPortNotConnected = 9

#PMUnknownError = 10

#PMMaxErrorCodes = 50

The Port Manager API

Two public functions are provided by the port manager:

\PortManager.PortConnectSem

Description

A generic port connection / semaphore for use within drivers that returns the stream for the caller to use.
Returns

TRUE when the port semaphore has been granted

A numeric error code if that semaphore will not be granted

Nothing (Invalid) if waiting for the port semaphore
Usage Script Only.
Format \PortManager.PortConnectSem(PortObj [, RetError, pStream, ReadOrWrite, AllowMultipleConnections]);
Parameters  
PortObj
Required. The object of the port tag from which we require a connection and semaphore.
RetError
Optional. A pointer to a value that will contain one of the defined error codes at the conclusion of the operation.
pStream
Optional. (But recommended.) Used to allow PortConnectSem to return the Stream on which data should be transferred back to the driver.
ReadOrWrite
Optional. (But recommended.) Used to set the semaphore type for the request and should be set to the constants #ReadSem or #WriteSem.
AllowMultipleConnections
Optional. (But recommended.) Used to tell PortConnectSem() whether the driver supports multiple connections

 

\PortManager.GetErrorMessage

Description

Returns a text error message for a given error code.
Returns Text
Usage Script Only.
Format \PortManager.GetErrorMessage(RetError);
Parameters  
RetError
Required. The error code returned in the RetError parameter of a call to PortConnectSem

Example:

 
The following code sends text “Hello Detroit!!!” out through port tag defined by parameter “PortTag” 
every 1 second after the port has opened and has the semaphore.  If an error is encountered, the module 
returns the text value of the error to the calling module.
 
Connect_And_Send [ 
   { Get the object value of the port defined in driver tag parameter PortTag }
  PortObj = Scope(Root, PortTag);

   { Attempt connection and get the semaphore }
  OkToSend = \PortManager.PortConnectSem(PortObj, RetError, &Stream, #WriteSem, FALSE)
 
   { When connected & we have the semaphore, OK to send every 1 second }
  If TimeOut(OKToSend, 1);
  [
    SWrite(Stream, “Hello %s!!!\r\n”, PickValid(\GreatRockTown, “Detroit”));
  ]
 
   { Error was detected on port, all done with it }
  If RetError AllDone;
  [
    Return(\PortManager.GetErrorMessage(RetError));
  ]
]

AllDone [
  { Nothing to see here, keep moving along }
]