![]() |
NORSYS SOFTWARE © 2002 | NETICA API | C   VERSION   2.15  |
void ReadCase_bn ( | caseposn_bn* case_posn, stream_ns* file, const nodelist_bn* nodes, long* ID_num, double* freq ) |
Reads a set of findings (i.e., 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 WriteCase_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 WriteCase_bn or ReadCase_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 ReadCase_bn call was replaced with: ReadCase_bn (..., NewStreamFile_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:
See also:
WriteCase_bn | Save it so that ReadCase_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 | |
NewStreamFile_ns | To create the stream_ns for the file argument |
Example:
// Usage of ReadCase_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 = NewStreamFile_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 ReadCase_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);