perm filename RSCAN.DOC[USE,CSR] blob sn#666284 filedate 1982-07-02 generic text, type T, neo UTF8
 Stanford SCORE, TOPS-20 Monitor 5(4742)-4
@csd.davidson 
 Job 29 on TTY126 2-Jul-82  3:58PM
 Previous LOGIN: 2-Jul-82  3:48PM
 End of LOGIN.CMD.2
@jsys rscan

                             RSCAN     JSYS 500


   Places a text string in, or reads a text string from, the job's rescan
   buffer  (an  area of storage in the Job Storage Block).  This facility
   allows a program to receive information that will be used  as  primary
   input  for  another program before this other program reads input from


   the terminal.

   The RSCAN call has two steps:  the acceptance and the use of the  text
   string.   Each  step has a different calling sequence.  The first step
   is to accept the text string to be used as input  and  to  place  this
   string  in  the  rescan  buffer.   The  calling sequence for this step
|  specifies, in AC1, a pointer to the text string  to  be  input.   Note
|  that  the  string  stored in the rescan buffer is terminated by a null
|  byte.

   The second step is to cause the string to be available to the  program
   for  reading  via  the BIN call.  The calling sequence for this second
   step specifies a function code of 0(.RSINI) in AC1  to  indicate  that
   the  last  string  entered  at  command  level  from  the  terminal is
   available for reading.  The  program  executing  the  RSCAN  call  can
   determine  when  the  data has been read by issuing a function code of
   1(.RSCNT), which returns the number of  characters  remaining  in  the
   buffer.

   In other words, the first RSCAN call  specifying  a  new  text  string
   stores  the  string  in  the rescan buffer but does not cause it to be
   read.  A second RSCAN call must be given  before  the  string  can  be
   read.   This  second RSCAN causes the system to provide input from the
   most recent string stored and can be  given  only  once.   After  this
   second  RSCAN,  nothing  will  be  read  from  the rescan buffer until
   another RSCAN call specifying a different text string  is  given.   In
   addition,  the  job  receives input from the rescan buffer only if the
   source for input in the  BIN  call  is  the  JFN  of  the  controlling
   terminal.   Therefore,  if  the  source  for  input  is other than the
   controlling terminal, input will not come from the rescan buffer.

   ACCEPTS IN AC1:  byte pointer to a new text string, or 0 in  the  left
                    half and function code in the right half

   RETURNS     +1:  failure, error code in AC1

               +2:  success

   The defined functions are as follows:

   Function       Symbol                   Meaning

       0          .RSINI    Make the data  in  the  buffer  available  as
                            input  to any process in the current job that
                            is  reading   data   from   its   controlling
                            terminal.

       1          .RSCNT    Return the number of characters remaining  to
                            be  read  in  the buffer.  This function does
                            not cause data to be read;   it  is  used  to
                            determine  when  all  the  data has been read
                            after making the data available.

   On a successful return, AC1 contains an  updated  byte  pointer  if  a
   pointer  was given in the call.  Otherwise, AC1 contains the number of


   characters in the rescan buffer or 0 if there are no characters.

|  To clear the RSCAN buffer, supply a byte pointer (in AC1)  to  a  null
|  string.

   RSCAN ERROR MNEMONICS:

   RSCNX2:   invalid function code
@