RSTAT

Return information about the last record read

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

xcall RSTAT(size[, term_char])

Arguments

size

The variable that will be returned with the size of the last record read. For READ and READS operations, the returned size doesn’t include the record terminator that ended the input operation. (n)

term_char

(optional) The variable that will be returned with the character that terminated the input operation, loaded left-justified over blanks. Term_char should be a one-character field. (a)

Discussion

The RSTAT subroutine returns the size and terminating character of the last record read by a GET, GETS, READ, READS, ACCEPT, W_DISP, W_DISP(WD_READS), or W_FLDS(WF_INPUT) operation.

The RSTAT subroutine is similar to the RSTATD subroutine, except that the record terminator is returned as the terminating character code (a numeric field) in RSTATD.

You can also obtain the same information using the %RSIZE (or %RDLEN) and %RTERM (or %RDTRM) intrinsic functions. %RSIZE returns the length of the last GET, GETS, READ, READS, or ACCEPT statement or one of the Synergy windowing API I/O operations, while %RTERM returns the terminating character of the last record read, without the overhead required by an external subroutine.

RSTAT returns a null character in term_char after a READS that does not require an explicit terminator is executed and the input field is full (after auto termination). For files, the terminator is always a null character.

The ACCEPT statement reads only one character or control code sequence per execution.

In Synergy .NET, you cannot use RSTAT in multi-threaded scenarios where a channel number has not been not specified.

See also

• RSTATD routine
• %RSIZE routine
• %RTERM routine

Examples

The following example gets the length and the terminating character of user input and displays that information to the screen.

.define TTCHN           ,1
record
    inarea              ,a500
    afld                ,a5
    flng                ,d1
    inlng               ,d5
    trmchr              ,a1
    dcml                ,d3
proc
    open(TTCHN, i, "tt:")
    repeat
      begin
        display(TTCHN, "Enter an input string:  ")
        reads(TTCHN, inarea)  [eof=done]
        xcall rstat(inlng, trmchr)
        afld = inlng, "zzzzx" [left:flng]
        xcall decml(trmchr, dcml)
        display(TTCHN, "... input was ", afld(1, flng),
  &             "long, trmchr was ", %string(dcml))  
        forms(TTCHN, 1)
      end
done,
    stop
end