AIDA_hRestoreStackEx

The AIDA_hRestoreStack function restores an AIDA stack formerly saved by AIDA_boSaveStack.

handle AIDA_hRestoreStack(
  const xchar *xsFileName,
  xchar *xsComment,
  dword *pdwCommentBufferSize
  dword *pdwStackLevels
  dword dwRestoreOptions
);

Parameters

xsFileName

Filename of the configuration file to be used. The filename has to be a valid name for the target operating system. It has to be passed without extension.

xsComment

Pointer to a buffer for a comment loaded from the configuration file.

pdwCommentBufferSize

Pointer to variable that contains the size of the buffer passed in xsComment.

pdwStackLevels

When this Pointer is not NULL, AIDA_hRestoreStack will set the given variable to a bitmask that represents all levels of components loaded by the application when the stack was saved.

dwRestoreOptions

A flag field describing the options to be used for stack restoring. Possible values are:

AIDA_nStackCreateRestoreNormal
AIDA_nStackUnmanagedIdMode
AIDA_nStackForcedOffline
AIDA_nStackRestoreReplacements
AIDA_nStackRestoreReplRemote

AIDA_nStackCreateRestoreNormal is used when no other flag is needed.

AIDA_nStackUnmanagedIdMode must be set when the event id manager shall not be used.

AIDA_nStackForcedOffline must be set when the stack shall be forced offline after restoring the stack.

AIDA_nStackRestoreReplacements must be set when parameters shall be replaced according to the replacement table during the restore operation.

AIDA_nStackRestoreReplRemote must be set when parameters shall be replaced according to the replacement table during the restore operation. In contrast to AIDA_nStackRestoreReplacements the environment variables are read from the stack level where the corresponding parameter is stored. Thus when using network components in a stack configuration the replacement of remote parameter values is done according to the remote environment.

Return Values

AIDA_hRestoreStackEx returns a handle for the restored stack. It will store the comment in xsComment and will set *pdwCommentBufferSize to the true size of the comment including the terminating '\0' character. xsComment will be terminated with a '\0' character in any case. When pdwCommentBufferSize ≥ size of xsComment buffer the comment stored in xsComment had been truncated. Comments are limited to a buffer size of AIDA_nMaxCommentBufferSize (see AIDA_boSaveStack).

If the function fails, the returned value is NULL. The application can retrieve the error code using AIDA_iGetError.

Even if the function succeeds an error code may be set. This happens when during the restoration of a stack a loaded component refuses one of the saved parameters to be set. Therefore it is recommended to check the error code even when the function returns a handle.

Remarks

Attention: Stack manipulation functions and component configuration functions may not be called simultaneously from different threads with the same handle or otherwise will cause unpredictable results.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Linux: Requires a kernel supporting ELF binaries.
  Header: Declared in bsk_aida.h, also requires portab.h.
  Import Library (Windows): Use BSK_AIDA.lib.

See Also

AIDA Overview, AIDA Stacks Licensing/Authentication Overview, AIDA Functions, AIDA_hsGetPlainErrMsgX, AIDA_vFreeErrMsgX, AIDA_hCreateStack, AIDA_hCreateStackEx, AIDA_boDeleteStack, AIDA_boSaveStack, AIDA_hRestoreStack, AIDA_hRestoreStackRaw, AIDA_pastSetReplacementTable, AIDA_bAddToStack, AIDA_boRemoveFromStack, AIDA_xsComponentName