long Load(File_Identifier File_ID, long Load_Flags);

Parameters

• File_Identifier File_ID: A file identifier (generally filename or memory file descriptor).
• long Load_Flags: Flags that control deserialization.

Return Values

• Nonnegative:  Load result code.
• Negative: Error code.

Remarks

This function loads a data file into memory, performing deserialization and mapping the appropriate number of nodes.  File_ID, a platform-dependent type, identifies the file.  Load_Flags contains flags that control the deserialization process.

Upon success, the current node becomes the top-level node if the load was not paused (see notes on incremental loading below).

The following flags are defined for Load_Flags:

• BLSF_IGNORE_PAUSE_POINTS = 1: Ignore pause points (treat implementation file as if no constructs had the “discardable” attribute).
• BLSF_FORCE_NO_FRAGMENTATION = 2: Treat the top-level node as if it had the “nofragment” attribute, which forces the entire file to be loaded at once, in a contiguous memory block. If no available memory block can singularly accommodate the entire file, this function call fails.

If a pause point is reached and BLSF_IGNORE_PAUSE_POINTS is not set, the load is treated as a success, even though not all of the file was loaded. In this case, the return value is BAR_DESERIALIZATION_PAUSED. The current node becomes the node that caused the pause (the parent of a list that has the “discardable” attribute).

If another file was already loaded at the time of this function call, it is unloaded automatically before loading the specified file.

The return value indicates the result of the load. This is the same value returned by Get_Last_Error.

The function can fail for any of the following reasons:

• The top-level node has a false validation condition (validation failure).
• The file cannot be deserialized due to critical error.
• The security settings blocked access to the file (BAR_Services opt-in and opt-out paths control security settings).
• There was a file open error or file read error.
• The total read time or total opcode cycles used in deserialization exceeded the limits set by BAR_Services.

If the function call is successful, all functions pertaining to node navigation, node information, data reading, data writing, and node insertion and deletion become available.

If the function call fails, all functions pertaining to node navigation, node information, data reading, data writing, and node insertion and deletion become unavailable. Memory allocated during the function call is freed in the event of failure.

Compatibility

	All Platforms	Win32 C++ LIB
BAR version	1.1	1.1
	All Platforms	Win32
BARfly version	n/a	n/a

  See also:  [BAR type lookup functions] [BAR loading and saving functions] [BAR node navigation functions]
[BAR node information functions] [BAR data reading functions] [BAR data writing functions] [BAR miscellaneous functions]