#%TITLE% WAGOSER.MAC 

#%DESCRIPTION%
# Macro to handle a WAGO serial line module through the WAGO Device Server
# and the %B%wagocore.mac%B% macros. Therefore a call to %B%wagosetup%B%
# must have been done before using these macros. The serial line
# is identified by the logical name given in the Device Server resources
# to the WAGO module.
#
#  %BR%
#  %BR%
#
#%EXAMPLE%
#  %DL%
#  %DT%wagosetup wcid33a 
#  %DD%Declares the Wago I/O stations named wcid33a as being
#      accessible through macro set.
#  %DT%p wago_ser_par("sl","timeout")
#  %DD%Print the timeout for the logical channel named \"sl\"
#  %DT%p wago_ser_get("sl")
#  %DD%Read a string from the serial line associated to 
#      logical channel named \"sl\"
#  %DT%byte array dd[10]; array_op("fill",dd); p wago_ser_put("sl",dd)
#  %DD%Send bytes over the the serial line.
#  %XDL%
#

#%UU%(logname,s)
#%MDESC%
# Writes the string %B%s%B% to the serial device with logical 
# name %B%logname.%B% 
#  %DL%
#  %DT%wago_ser_put(logname,d [,cnt])
#  %DD% Writes the byte data array %B%d%B% to the serial device
#       with logical name %B%logname.%B%
#       By default, the entire array will be sent. The optional
#       third argument %B%cnt%B% can be used to specify the number of array
#       elements to send.
#  %XDL%
#
def wago_ser_put(sl,s,cnt) '{
 local i
 local n

 _wago_ser_checkch(sl)

 # A string to send over the serial line
 if(whatis("s")&0x00200000) {
  n=length(s)
  for(i=1;i<=n;i++) {
   wago_writech(sl,asc(substr(s,i,1)))
   sleep(0.001)
  }
  exit
 }

 # A data array to send over the serial line
 if(whatis("s")&0x00010000) {
  n=(whatis("cnt")&0x08000000)?array_op("cols",s):cnt
  for(i=0;i<n;i++) {
   wago_writech(sl,s[i])
   sleep(0.001)
  }
  exit
 }

 p "ERROR: wrong argin type, only string and data array are supported"
 exit
}'


#%UU%(logname)
#%MDESC%
# Reads and return a string from the serial channel with logical
# name %B%logname.%B%
# Returns as many characters as are already available in the 
# receiving queue.
# Returns a null string if no characters become available
# within the timeout period set with %B%wago_ser_par()%B%
#
def wago_ser_get(sl) '{
 global WAGOSL_TO[]
 local  ch
 local  s
 local  t0

 _wago_ser_checkch(sl)
 _wago_ser_checkto(sl)

 for(s="",t0=time();(time()-t0)<WAGOSL_TO[sl];)
 {
  ESRF_ERR=-1
  ch = wago_readch(sl)

  # The DS return one character
  if(ESRF_ERR == 0) {
   s = sprintf("%s%c",s,ch)
   t0=time()
   continue
  }

  # Expected error from the DS: empty receiving buffer
  if(ESRF_ERR == 71) {
   if(s!="") break;

   sleep(.1)
   continue
  }

  # At this point there is an unexpected error from the DS
  p TACO_ERR_MSG 
  break
 }
 return s
}'


#%IU%(logname)
#%MDESC%
# Initialize timeout for the channel %B%logname%B%
#
def _wago_ser_checkto(sl) '{
 global WAGOSL_TO[]
 if(whatis("WAGOSL_TO")&0x08000000) { WAGOSL_TO[sl]=2 }
}'


#%IU%(logname)
#%MDESC%
# Check if the %B%logname%B% has already configured with %B%wagosetup%B%
#
def _wago_ser_checkch(sl) '{
 if(!(sl in WAGOKEYS)) {
  p "ERROR: WAGO logical channel \""sl"\" not configured"
  p "HINT : use \"wagosetup\" first"
  exit
 }
}'



#%UU%(logname,"?")
#%MDESC%
#  Return the document list of possible argins
#  %DL%
#  %DT%wago_ser_par(logname,"timeout" [,t])
#  %DD% Returns or sets the read timeout for the channel %B%logname%B%
#       The units are seconds
#  %DT%wago_ser_par(logname,"flush")
#  %DD% Empty serial receiving queue and returns the number of characters
#       that were in the queue
#  %XDL%
#
def wago_ser_par(sl,cmd,arg) '{
 global WAGOSL_TO[]
 local  i

 _wago_ser_checkch(sl)

 if(cmd=="?") {
  return "timeout"
 }

 if(cmd=="timeout") {
  _wago_ser_checkto(sl)
  if(!(whatis("arg") &0x08000000)) { sscanf(arg,"%f",WAGOSL_TO[sl]) }
  return WAGOSL_TO[sl] 
 }

 if(cmd=="flush") {
  for(i=0;;i++) {
   ESRF_ERR=-1
   wago_readch(sl)
   if(ESRF_ERR != 0) { break }
  }
  return i
 }

 p "ERROR: unknown argument \""cmd"\""
 p "HINT : use: wago_ser_par(\""sl"\",\"?\")"
 return ""

}'

#%MACROS%
#%IMACROS%
#%AUTHOR% MP BLISS (Original 7/09).
#%BR%$Revision: 1.0 $ / $Date: 2009/08/03 13:16:55 $
#%TOC%