#read()

DESCRIPTION
    read in the next line of input from the file handle associated with some
    open file or process, assigning the input line to the special variable
    $rdlin (also $rdline or $readline), returning the number of characters
    read, else ERR on error

SYNOPSIS
    #read(F)

ARGUMENTS
    F - a filehandle (or process handle) (all caps)

EXAMPLES

outputfile(C, F)        // send all output from file (F) to communications
                        // channel (C)
                        // (C) is the comm channel (e.g., mail, syslog, print)
                        // (F) is the file (e.g., "=crontabs/$name")
                        // sample use:  =outputfile(mail, "=crontabs/$name")
                        if #fopen(OUTPUTFILE, (F), "r")
                                while #read(OUTPUTFILE) > 0
                                        output (C) $rdlin
                                endwhile
                                do #fclose(OUTPUTFILE)
                        fi

readvals(F, V, S, N)    // open the file (F), for each input line, #split()
                        // on separator(s) (S) into (N) fields, assign to
                        // associative array (V)[], with the first field in
                        // the referenced file as the key
                        // (F) is the file (e.g., =passwd; without quotes)
                        // (V) is the variable name (e.g., pfield)
                        // (S) is the field separator (e.g, ":"; with quotes)
                        // (N) is the number of assigned values per line,
                        //   (e.g., 6; note that (N) should be one less
                        //   than the actual number of data items per line,
                        //   since the first data item is the key, and all
                        //   remaining items are the assigned values)
                        // sample use: =readvals(=objdir/ProcessTimes.obj, minsproc, "  ", 3)
                if #fopen(READVALS, "(F)", "r") != #err()
                        while #read(READVALS) > 0
                                set #nrv = #split($rdlin, (S)) - 1
#ifdef debug
                                if #nrv < (N)
                                        =outputmail "Too few vals ($text(#nrv)): $rdlin"
                                fi
#endifdef
                                for #irv=1 #irv<=(N) #irv+=1
                                        set $(V)["$trim($1) $text(#irv)"] = $trim($[#irv+1])
                                endfor
                        endwhile
                        do #fclose(READVALS)
#ifdef debug
                        for $krv in #keys($(V))
                                output "$krv $(V)[$krv]"
                        endfor
#endifdef
                else
                        output mail "Can't open (F) for reading!"
                        quit
                fi

SEE ALSO
    #fopen()
    #fclose()
    #popen()
    #pclose()
    #write()

    Numerical Functions
    String Functions