netUdoc.nb documents the functions in the Package netUtil.m 
Notebook Version 2.0
Steve Hunka, University of Alberta
steve.hunka@ualberta.ca
Mod. Date: Oct 25/97

Notes

The conversion of a Package from V2.2 to V3.0 results in the removal of comments defined by (* ....*). The Version 2.2  of netUtil.m contained documentation as comments and were automatically removed in conversion to Version 3.0.  This Notebook now provides the documentation.
In V3.0 FileNames[fname] returns file names prepended with a colon, while in V2.2 no colon is present.  Functions getFdata, rcvrExpr, and rprtFdata were changed to accommodate this incompatible revision. The changes will work satisfactorily in V2.2.

kbin3[q_,p_]; q is the directive (question) as a string. If p is any integer then an integer is to be input; if p is any real value then a real value is to be input; if p={n} then a n element vector is expected; if p={r,c} then a matrix with r rows and c columns is expected. If the input is inappropriate a message is given and the question is posed again.  If the input is appropriate it is returned.
Mod. Date: Mar 24/96

kbinstrg[q,p] q is a string for a directive (question). p contains acceptable answers in
 the form of a list,eg., p={{"ans1"},{"ans2"},....}. If the input is in the list of acceptable answers,  it is returned. If the input is list the directive is posed again.
Mod. Date: Mar 24/96

inpvec[r,n,ty] presents directive "Type n element vector of "ty" indices" and
 checks the vector elements being in the range (r)={min,max}.
r is a vector of the acceptable range
n is the acceptable number of elements in the vector
ty is a string describing the nature of the indices to be input
If the range is exceed, the directive is presented again. If n elements are not present, the function kbin3 will give a message and request a new vector.
Calls: kbin3
Returns: an acceptable input vector
Mod. Date: March 25/97

pmat2[m,pc,rch] prints a 2D matrix with either numbered rows and columns or
 with labelled rows and columns, in units of pc columns 
m     is the matrix to print
pc    is the number of columns to use across the window
rch   is optional; if present it contains the row and column headings in the 
       following format: {{"a","b","c",...},{"A","B","C","D",....}} where
       Part 1 gives the row headings, and Part 2 gives the column headings. 
       Part 1 must have as many headings as rows of the matrix, and Part 2
       must have as many headings as the columns of the matrix.
       If the argument rch is not used, the row and column labels
       will be the integer sequence starting at 1, and the column digits for any 2nd
       part of the matrix printed will continue the digit sequence.
 Mod Date: Jan 27/96

genrch[rh,ch,rc] generates row and column headings for displaying a 2D matrix
rh   is the string prefix for row headings
ch   is the string prefix for the column headings
rc   is the Dimensions of the matrix as a vector
The prefix for row and columns will be followed by digits starting at 1.
Mod. Date: Feb 14/97

rndoff[n,d] rounds off the value n to d decimal digits*)

plotnLists[m,tl,xu,ps,pm,pn] plots a colored line for each column of m.
 The values in the column are y coordinates and the x coordinates are taken
 to be from 1 to the number of rows of the matrix.
tl is a string title for the plot, 
xu is the string label for the x-axis
ps  set to 1 for individual plots for each col; 0 for no individual plots
pm set to 1 for one plot holding multiple lines; 0 for no plot
pn  (Optional) set to 1 for line numbers at end of lines when pm=1; else 0 
For single plots (ps=1), the title is appended to a plot sequence number.
The colors are rotated through the following color sequence:(1) black, (2) 
blue (3) green, (4) cyan, (5) red, (6) magenta, (7) yellow, (8) dark blue, 
(9) dark green (10) turquoise, (11)brown, and (12) purple. (Colors numbered 8
to 12 may vary with different monitors.) To get a simple example of the colors
used, do plotnLists[Table[Range[0,11],{2}],"Legend","units",0,1,1]  or use the
function plotLegend.
Mod. Date: Mar 20/97

plotLegend[nl]: plots a color legend for the lines plotted by those functions
  using the same variable colr for color of lines. (colr is padded with extra (0,0,0)
  to accommodate y=0). nl is the number of lines to plot; if nl<=1 no legend is
   plotted.
   Mod. Date: Mar 25/97

getFdata: reads data from a file
  User Input: 
  The user is asked to input the name of the file holding the file data; if the file is
   found a message is given; if the file is not found a message is given and the user
   is asked to give another name. If the user enters quit at the point of entering a
   file name, a Return[{0,0}] is made. If the file is available the user is asked whether
   to use all the data or only part of it. If the user enters "all", all data is read;
   if "part" is entered, the user is asked to give the starting point (record) in the
   file and the ending point for which the data is wanted.
Calls: kbin3, kbinstrg,timeDate
Returns: data from the file read, and extnt a 2 element vector of starting and
             ending position for the data read. If "quit" is entered when a file
             name is requested, {0,0} is returned and no data is read.
Note: Calling function may need to check Part[Dimensions[data],1] to get 
         actual data records read as user may input an ending record beyond the
         number of records actually available. 
Mod. Date: Oct 17/97

timeDate[ts] prints month day,year at hour:minutes. ts is vector returned
  by Date or FileDate.

openFna[fc_,p_] get file names and open the files; fc is structure holding a
  description of the contents of files to be set up. It has the form:
       {{1,{"file contents description"}},{2,{"file contents description"}},..}
 p determines the form of the open:
 p=0, OpenRead; p=1,OpenWrite; p=2,OpenAppend; p=3,OpenTemporary
 The user is queried as to whether a file with the designated file contents is to
 be set up. If a file is to be set up, a file name is requested. If the file already
 exists, the user is queried whether to continue, if the reply is y (yes) and p=1, 
 the existing file will be over written, if p=2, the existing file will be appended.
 If the reply is n (no) a new file name is requested.
 The function returns a structure of the form of fc but only for those
 files opened. This structure has the form
   {{1,{filename},{2,{filename}},..} 
 and holds the file name for each file opened as requested in fc.
Calls:kbinstrg
Mod. Date: Mar 20/96

rcvrExpr[rid___,rds_:0] to recover expression stored in the form
 {{rid,date-time,{expression}}, {rid,date-time,{expression}}....}.
rid is optional; if present it is a run ID string assigned by the user at the time
     the expression was written to the file. It must be given between enclosing
     quotation marks.
rds is a 14 digit date-time stamp assigned at the time the file was written;
     rds is set to 0 if not present.
Use rcvrExpr[] to get last expression; use rcvrExpr[rid, date-time stamp] to 
get a specific expression as defined by rid and the date-time stamp.
User Input: 
a) the name of the file in quotation marks; if quit is entered, the function stops;
 if the file is not found, a message is given and a file name is requested again.
Calls: timeDate
Returns: an expression 
Mod. Date: Oct 17/97

rprtFdata is used to obtain a list of the runID and date-time stamp of 
expressions stored in a file, such as the random seeds or last epoch data 
saved while running a network simulation. It assumes each expression is 
stored in the format {id,date-time-stamp,{expression}}, where id is a string, 
date-time-stamp an integer, and expression is a Mathematica expression. 
User Input: name of file 
Displayed: whether the file was found and its creation date. Information about
 each expression is printed and includes, the expression's string ID, date-time
  stamp, Length, Dimensions, and Head.
Calls: timeDate
Mod. Date: Oct 17/97

saveExpr[x] save the Mathematica expression x to a file in the format
{expID,date-time-stamp,expression}; normally x would have its own enclosing
 { and }. The date-time-stamp is a 14 digit integer made up of from left to right,
 year,month,day,hour,minute,second created at the time the expression was
 saved. The file opened for writing is opened as "OpenAppend" so that 
 expressions may be accumulated in the one file. Use function rprtFdata to get 
 a summary of expressions in a file, and rcrvExpr to recover an expression. 
User Input: expID
Output: expID, date-time-stamp, file to which x was saved.
Calls: openFna
Mod. Date: Mar 20/96