void ReadNetFindings_bn ( caseposn_bn*  case_posn,   stream_ns*  file,   const nodelist_bn*  nodes,   long*  ID_num,   double*  freq )

Reads a set of findings (i.e., a case) from a file containing one or more cases.

The case file is an ascii text file with each case on one row, and the first row being the list of nodes as column headings. Each entry is separated by a comma, space or tab. Such a format is quite common; it can be produced by a spreadsheet program like Excel, or by the Netica function WriteNetFindings_bn.

It only reads findings into the nodes listed in nodes. Other nodes in the net will not have any new findings entered, even if findings for them appear in the file. All the nodes of nodes must be from the same net. It is okay if nodes contains some nodes not mentioned in the file. If nodes is empty, no new findings will be entered.

WARNING: It does not retract findings that are already in nodes, and will even generate errors if the findings in the file are inconsistent with findings already in nodes. So you probably want to call RetractNetFindings_bn first.

In general it reads from file the case at *case_posn, or if *case_posn is NEXT_CASE it reads the next case after the last one read from file, and sets *case_posn to the position of the case it just read. In detail:

  Called with:    File condition:    Action taken:
          
  case_posn = NULL    - file has no cases    generates error
      - file has 1 or more cases    reads first case
          
  *case_posn = FIRST_CASE    - file has no cases    returns with *case_posn = NO_MORE_CASES
      - otherwise    reads first case sets *case_posn to it
          
  *case_posn = NEXT_CASE    - all cases read    returns with *case_posn = NO_MORE_CASES
      - otherwise    reads next case sets *case_posn to it
          
  *case_posn = NO_MORE_CASES        generates error
          
          
  *case_posn = case    - indicated case is in file    reads indicated case
      - indicated case isn't in file    generates error

Make sure *case_posn is initialized on entry. If you want to read cases by random access, *case_posn should be set to a value previously returned by WriteNetFindings_bn or ReadNetFindings_bn (not the case ID_num).

When reading multiple sequential cases from the same file using NEXT_CASE, the stream_ns structure keeps track of the current file position. So different parts of your program, or different threads, can read from the same file in an interleaved way without interference, provided they each have their own stream_ns. But each sequential series of reads must use a single stream_ns (so the example below wouldn't work if the ReadNetFindings_bn call was replaced with: ReadNetFindings_bn (..., NewFileStream_ns (filename, env), ...); because that would make a new stream_ns each time it was called).

If ID_num is non-NULL, then on return *ID_num will be set to the ID number of the case, or -1 if it doesn't have one. If freq is non-NULL, then on return *freq will be set to the frequency (i.e., multiplicity) of the case stored with that case, or 1.0 if it doesn't have one.

This function doesn't modify or free the nodes list passed to it.

Version:

This function is available in all versions.
In versions previous to 2.26, this function was named ReadCase_bn.

See also:

WriteNetFindings_bn    Save it so that ReadNetFindings_bn can read it back
RetractNetFindings_bn    You may want to call this before reading a case
GetNetNodes_bn    Usually use this for the nodes argument
NewFileStream_ns    To create the stream_ns for the file argument

Example:

// Usage of ReadNetFindings_bn usually follows a pattern like that below.
// 
// This example is meant as a template for functions that scan through 
// a case file.
//
stream_ns* casefile = NewFileStream_ns (filename, env, NULL); // create fresh local stream_ns
const nodelist_bn* all_nodes = GetNetNodes_bn (net);
caseposn_bn caseposn = FIRST_CASE;
while(1){
    RetractNetFindings_bn (net);                         // must retract old case first
    ReadNetFindings_bn (caseposn, casefile, all_nodes, NULL, NULL);
    if (caseposn == NO_MORE_CASES)  break;
    if (GetError_ns (env, ERROR_ERR, NULL))  break;
    //  ... do stuff with the case now entered ...
    caseposn = NEXT_CASE;                           // set it back to NEXT_CASE each time
}
DeleteStream_ns (casefile);