Initialize the library

saf_init is a macro defined in SAFinit.h.

Synopsis:

saf_init(PROPERTIES)

Description: The saf_init function must be called by the client to initialize the client’s interaction with the library and should be called before any other SAF-API function except functions that set the properties to be passed in the saf_init call.

Calling saf_init when the library is initialized has absolutely no effect, even when a new, different list of properties is specified.

The counterpart of saf_init is saf_final, which releases all resources held by the library. The saf_init function must be called after saf_final if the client desires to interact with the library again.

Since all SAF clients are required to call saf_init, we’ve chosen to wrap that function in a macro which also makes a reference to a global variable whose name is derived from the SAF version number. This variable is declared in the SAF library so that if an application is compiled with SAF header files which have a different version than the SAF library a link-time error will result. A version mismatch will result in an error similar to undefined reference to ``SAF__version_1_4_0`’ from the linker.

Return Value: The constant SAF__SUCCESS is returned for success; errors are returned as other values or by exception, depending on the setting of the error handling property in PROPERTIES (the default is to return an error number).

Parallel Notes: In parallel, saf_init is collective and must be called by all processes in the library’s communicator, which is MPI_COMM_WORLD by default. All processes must initialize the library with the same property values, although each may pass its own PROPERTIES argument.

If a new communicator is specified in the PROPERTIES argument then it will become the communicator for any database which doesn’t override this communicator. It is the maximal communicator in the sense that no database can be opened on a set of processors which is not a subset of those in the communicator declared in the properties passed here.

Issues: Verify that the set of processors which must participate in this call is either MPI_COMM_WORLD or the communicator passed in the PROPERTIES.

We might want to communicate to confirm that all procs pass the same properties.

See the private function, _saf_init, for the real implementation of this function

Calling saf_init after saf_final is currently not supported.

See Also: