NORSYS SOFTWARE © 2012     NETICA API     C   VERSION   5.04 

void ReadNetFindings2_bn ( caseposn_bn*  case_posn,   stream_ns*  file,   bool_ns*  add,   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 or retracted, even if findings for them appear in the file. All the nodes of nodes must be from the same net. If nodes is NULL, it means to operate on all the nodes mentioned in the file. It is okay if nodes contains some nodes not mentioned in the file. If nodes is empty, no new findings will be entered.

If add is FALSE, then it will first retract findings for all the nodes in nodes. If add is TRUE, then it will add these findings to the existing findings for the nodes in nodes. In either case, it will generate errors if the new findings are inconsistent with any remaining findings in the net.

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 ReadNetFindings2_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 ReadNetFindings2_bn call was replaced with: ReadNetFindings2_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.
In versions previous to 4.15, this function was named ReadNetFindings_bn and did not have the add parameter.

See also:

WriteNetFindings_bn    Save it so that ReadNetFindings2_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 ReadNetFindings2_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){
    ReadNetFindings2_bn (caseposn, casefile, false, 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);
Example 2:
// Save findings:
const nodelist_bn* nodes = GetNetNodes2_bn (net,0);
WriteNetFindings_bn (NewFileStream_ns ("C:\\MyWork\\t.cas"), nodes, -1, -1);
//...
// Later, read them back in:  (or read from any case file)
RetractNetFindings_bn (net);
ReadNetFindings2_bn (NULL, NewFileStream_ns ("C:\\MyWork\\t.cas"), false, nodes, NULL, NULL);