long Create_New(File_Identifier File_ID);

Parameters

File_Identifier File_ID: A file identifier (generally filename or memory file descriptor).

Return Values

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

Remarks

This function creates a new empty file in memory.  File_ID, a platform-dependent type, identifies the file.  A file by this name or other identification does not need to exist in secondary storage at the time of the function call.

After this function is called, the top-level block and its header structure (if present) are the only nodes the file starts with. The current node becomes the top-level node.

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

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

The function will fail if the engine runs out of memory while creating the file.

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]