bool Initialize(long Engine_Control_Flags,
  long Memory_Size,
  long Stack_Size,
  long Max_Read_Size,
  long Max_Write_Size,
  long Max_Deserialize_Output,
  long Max_Serialize_Output,
  long Max_Read_Time,
  long Max_Write_Time,
  long Max_Read_Cycles,
  long Max_Write_Cycles,
  long Max_Session_Cycles,
  long Max_Nodes,
  long Max_Registries,
  long Max_BARs,
  BAR_String Path_Opt_In,
  BAR_String Path_Opt_Out);

Parameters

• long Engine_Control_Flags: Flags that control the engine for this BAR_Services instance.  Can include any combination of the following:
  • BECF_FLAG_MEMORY_BOUNDS_TEST: This flag controls whether the BAR engine performs bounds-checking on pointers during script execution.
  • BECF_FLAG_STACK_OVERFLOW_TEST: This flag controls whether the BAR engine checks for stack overflow. Stack overflow is only likely if an implementation file has significantly nested subroutines or recursive function calls.
  • BECF_FLAG_MATH_DOMAIN_TEST: This flag controls whether the BAR engine checks for math domain errors in functions in BAR implementation files. If this flag is false, errors like division by zero or square root of negative numbers are handled by whatever exception handling processing the hosting environment has implemented.
  • BECF_FLAG_OPCODE_VALIDITY_TEST: This flag controls whether the BAR engine checks for errors in opcodes and mod bytes during script execution.
  • BECF_IGNORE_BREAKPOINTS: This flag controls whether breakpoint opcodes are ignored during script execution; this setting is used when debugging.
• long Max_Memory_Space: The amount of total memory, in bytes, to set aside for the BAR_Services instance and its children.
• long Stack_Size: The amount of stack memory, in bytes, to set aside for function calls for functions in BAR implementation files. This stack is managed internally; it is not related to any stack managed by the hosting environment.
• long Max_Read_Size: The default maximum file deserialization (read) size, in bytes.
• long Max_Write_Size: The default maximum file serialization (write) size, in bytes.
• long Max_Deserialize_Output: The default maximum allowable Deserialize method allocation size, in bytes.
• long Max_Serialize_Output: The default maximum allowable Serialize method allocation size, in bytes.
• long Max_Read_Time: The maximum time that can be taken up during deserialization, in milliseconds.
• long Max_Write_Time: The maximum time that can be taken up during serialization, in milliseconds.
• long Max_Read_Cycles: The maximum number of opcode-interpretation cycles that can be taken up during deserialization. If this figure is zero, there is no read cycle limit.
• long Max_Write_Cycles: The maximum number of opcode-interpretation cycles that can be taken up during serialization. If this figure is zero, there is no write cycle limit.
• long Max_Session_Cycles: The maximum number of opcode-interpretation cycles that can be taken up during a call to a function in a BAR implementation file.
• long Max_Nodes: The amount of nodes handles to reserve for the BAR_Services instance.
• long Max_Registries: The maximum number of BAR_Registry interfacial object instances that the BAR_Services object can host simultaneously.
• long Max_BARs: The maximum number of BAR interfacial object instances that the BAR_Services object can host simultaneously.
• BAR_String BAR_Path_Opt_In: The “opt-in” path string for disk files. The BAR engine shall only allow files to be serialized or deserialized if their absolute pathnames start with at least one of the path stems specified in this setting. If a null string is provided, the BAR engine shall not restrict access for any file as a result of this setting.
• BAR_String BAR_Path_Opt_Out: The “opt-out” path string for disk files. The BAR engine shall further restrict the paths specified by the BAR_Path_Opt_In setting by removing access from files whose absolute pathnames start with at least one of the path stems specified in this setting. If a null string is provided, the BAR engine shall not restrict access for any file as a result of this setting.

Return Values

• True:  Successful initialization.
• False:  Unsuccessful initialization.

Remarks

With the exception of BECF_IGNORE_BREAKPOINTS, engine control flags should be set to true to obtain “safe mode” status. However, the BAR engine does not require them to be set. It is recommended the flags be set because these engine control flags are the most effective way to “sandbox” the functionality of a single BAR_Services instance.

The "opt-in" and "opt-out" path strings have the following format:

PathString ::= (PathStem ‘;’)* PathStem

where PathStem is an absolute path stem. Multiple path stems use semicolons as separators. Any number of path stems can appear in the path string. The format of a path stem is platform dependent. Usually, an absolute path starts with an identifying drive or machine identifier, followed by a colon, followed by a combination of directory separator / directory name pairs.

Compatibility

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

  See also:  [BAR_Services Functions] [BAR_Registry Functions] [BAR Functions]