ObjectStore Release 5 Windows VAR Kit

Chapter 3 API Reference

The API descriptions that follow are based on the ObjectStore Release 5 version of OS_SETUP.DLL. The descriptions are organized alphabetically. Check the README.TXT file supplied with the VAR kit for the latest information about these APIs.

OS_BuildUnzipList

EXPORT BOOL OS_BuildUnzipList (char *InstallDir, char *InstallFrom,
BOOL Upgrading, long Flags, char *ZipFileName,
int iZipFile, long Mask)

Creates an internal list of files to be extracted from a given zip file.


`InstallDir`	Pathname of the target directory.
InstallFrom	Pathname of the directory containing zip files.
Upgrading	TRUE if upgrading an existing installation (the InstallShield script always sets this to FALSE).
Flags	Flags corresponding to the options being installed (as returned by OS_GetInstallFlags).
ZipFileName	Name of the zip file being unzipped.
iZipFile	Index of the zip file being unzipped (not currently used).
Mask	Mask associated with files in the zip file (as returned by OS_GetZipFile).
Return	TRUE if there are files to be extracted from this zip file, FALSE otherwise.

You must call this entry before attempting to extract files from a given zip file.

OS_CheckLogFile

EXPORT int OS_CheckLogFile (CHAR *FileName, int FileNameSize)

Attempts to determine if the Server log file has been initialized.


FileName	Pointer to a buffer to hold the Server log file pathname.
FileNameSize	Size of the Server log file pathname buffer.
Return	0 if a log file is not found. 1 if the log file is found in a file system file. 2 if the log is being maintained in the RAWFS partition.

OS_CheckRAWFS

EXPORT int OS_CheckRAWFS ()

Determines if any RAWFS partitions exist.


Return	TRUE if a RAWFS partition is found in the registry, FALSE otherwise.

OS_CheckServerStartup

EXPORT int OS_CheckServerStartup ()

Determines if the ObjectStore Server is currently set for autostartup.


Return	TRUE if the Server is in autostart mode, FALSE otherwise.

OS_DecompressZipFile

EXPORT BOOL OS_DecompressZipFile (char *InstallDir, char *InstallFrom,
                                  BOOL Upgrading, long Flags, char *ZipFileName,
                                  int iZipFile, long Mask)

Decompresses an entire zip file. Not currently used for the InstallShield installation.


InstallDir	Pathname of a target directory.
InstallFrom	Pathname of the directory containing zip files.
Upgrading	TRUE if upgrading an existing installation (the InstallShield script always sets this to FALSE).
Flags	Flags corresponding to the options being installed (as returned by OS_GetInstallFlags).
ZipFileName	Name of the zip file being unzipped.
iZipFile	Index of the zip file being unzipped (not currently used).
Mask	Mask associated with files in the zip file (as returned by OS_GetZipFile).
Return	1 if files are extracted, -1 otherwise.

This entry is obsolete.

OS_DeleteUninstRegKey

EXPORT BOOL OS_DeleteUninstRegKey (CHAR *szKeyPath, CHAR * szKey)

InstallShield adds an item to the list of uninstallable applications in the registry as one activity in the InstallShield ObjectStore installation process. However, ObjectStore cannot be uninstalled in the standard InstallShield mechanism, so Object Design deletes the key to avoid confusing the user. For this purpose, szKeyPath is

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall

and szKey is ObjectStore.

OS_DeleteUninstRegKey attempts to delete the key from
HKEY_LOCAL_MACHINE.

Return

TRUE if the deletion succeeded, FALSE otherwise.

Return	TRUE if the deletion succeeded, FALSE otherwise.

ObjectStore uses the InstallShield VerUpdateFile routine to install C++ run-time files. VerUpdateFile determines whether a reboot is required to complete installation. However, VerUpdateFile requires that the deinstall system be initialized (creating the Uninstall key) that OS_DeleteUninstRegKey later deletes.

OS_GetDefaultSrvrLogFile

EXPORT BOOL OS_GetDefaultSrvrLogFile(CHAR *pSvrLogFile)

Constructs a default pathname for the Server log file.


pSvrLogFile	Pointer to a 512-character buffer to hold the pathname. The pathname is based on the operating system (Win95 or WinNT), and on either the drive letter of the installation directory or the boot drive letter.

OS_GetDiskRequirement

EXPORT long OS_GetDiskRequirement (unsigned long Flags, char *InstallDir)

Returns an estimate of the amount of disk space required to install ObjectStore, based on the options represented by the Flags word.


Flags	As returned by OS_GetInstallFlags.
InstallDir	Pointer to a string containing the proposed installation directory.
Return	Estimated disk space requirements, in bytes.

OS_GetInstallFlags

XPORT long OS_GetInstallFlags (BOOL bLcClient, BOOL bLcServer, BOOL bLcDevo,
                                BOOL bCompDBMS, BOOL bCompSingle, BOOL bCompExamples,
                                BOOL bCompHTML, BOOL bCompPScript)

The entries that determine disk space requirements and lists of files to be installed use a flag, long, whose bits indicate which installation components should be copied, based on the various Boolean values passed in.


bLcClient	TRUE if a client is being installed, FALSE otherwise.
bLcServer	TRUE if a Server is being installed, FALSE otherwise.
bLcDevo	TRUE if this is a development installation, FALSE otherwise.
bCompDBMS	TRUE if ObjectStore itself is being installed, FALSE otherwise.
bCompSingle	TRUE if ObjectStore/Single is being installed, FALSE otherwise.
bCompExamples	TRUE if examples are being installed, FALSE otherwise.
bCompHTML	TRUE if HTML documentation is being installed, FALSE otherwise.
bCompPScript	TRUE if PostScript documentation is being installed, FALSE otherwise.
Return	Flag word with bits set as appropriate for files being installed.

OS_GetNextUnzip

EXPORT int OS_GetNextUnzip (char *UnzipName)

Gets the name of the next file to be unzipped.


UnzipName	Gets the name (relative to OS_ROOTDIR) of the next file to be extracted from the zip file. Back-slash characters are returned as forward slashes.
Return	0 if there are no more files to be unzipped from this zip file, otherwise, the number of bytes of disk space required for this file.

OS_GetRegistration

EXPORT int OS_GetRegistration (CHAR *pRegisterType, CHAR *pRegEntry, int RegEntrySize, int 
LocalMachBool)

Returns ObjectStore registration registry information.


pRegisterType	Specific key value to be retrieved (see below).
pRegEntry	Pointer to a buffer to hold the value.
RegEntrySize	Size of the value buffer.
LocalMachBool	If 1, the value is retrieved from HKEY_LOCAL_MACHINE; otherwise, the value is retrieved from HKEY_CURRENT_USER.
Return	Always returns 1.

Values are retrieved from

HKEY_LOCAL_MACHINE\SOFTWARE\Object Design Inc.\ObjectStore.4.0\Registration

HKEY_CURRENT_USER\Software\Object Design Inc.\ObjectStore.4.0\Registration

Values stored in HKEY_LOCAL_MACHINE include all of these that are literal strings:

Company
Install From
License Type
ObjectStore Install Directory
ObjectStore/Single Directory
ObjectStore Examples Directory
ObjectStore HTML Documentation Directory
ObjectStore PostScript Documentation Directory
Program Folder Name

Values stored in HKEY_CURRENT_USER consist only of

User Name

OS_GetServerParameter

EXPORT int OS_GetServerParameter (const CHAR *Key, CHAR *Value)

Gets the current value of an ObjectStore Server parameter.


Key	Points to the parameter name.
Value	Points to a 512-character buffer to receive the value.
Return	0 if the parameter is known, -1 otherwise.

Server parameters are stored under the registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Object Design Inc.\ObjectStore.4.0\Server

Note that a parameter can be known but have a null value. In this case, the OS_GetServerParameter returns 0 but the value buffer will contain a null string.

OS_GetZipFile

EXPORT int OS_GetZipFile(char *ArchiveName, int Which, long *Mask)

Gets the name of the next zip file and a mask, corresponding to the flags (see OS_ZipLogFiles) associated with the files in the zip file.


ArchiveName	Pointer to a 256-character buffer to hold the name of the zip file.
Which	Should start at zero and be incremented after each call to OS_GetZipFile.
Mask	Pointer to a long, which is set to the flags of the files stored in this zip file.
Return	>= 0 if an archive corresponding to Which exists, -1 otherwise.

OS_InitDLL

EXPORT int OS_InitDLL (HWND hWnd, CHAR *pAppPath)

Initialize DLL for execution

The first DLL entry called.


hWnd

Main installation window InstallShieldGetWindowHandle 
(HWND_INSTALL): used when displaying installation, setup, and error dialogs.


pAppPath

Directory containing OSCP437.DLL (or equivalent). The OSCP xxx.DLL should correspond to the OEM code page of the system running setup.


Return

Always returns 0.

Initialize DLL for execution	The first DLL entry called.
hWnd	Main installation window InstallShieldGetWindowHandle (HWND_INSTALL): used when displaying installation, setup, and error dialogs.
pAppPath	Directory containing OSCP437.DLL (or equivalent). The OSCP xxx.DLL should correspond to the OEM code page of the system running setup.
Return	Always returns 0.

OS_InitLog

EXPORT int OS_InitLog (CHAR *Logfile, BOOL bSilent)

Initializes the ObjectStore Server and the Server log file.


Logfile	Pathname of the log file. This is ignored unless bSilent is TRUE, in which case it must be a file system path. It is not currently possible to silently initialize the Server if the Server log file is stored in the RAWFS.
bSilent	Set to TRUE to initialize the log without interacting with the user (used for a Typical installation).
Return	TRUE if the log file was initialized, FALSE if the user canceled from dialog or if initialization failed. Note that an error dialog is displayed by OS_InitLog if the initialization fails.

OS_IsUserAdmin

EXPORT BOOL OS_IsUserAdmin ()

Attempts to determine if the current user is an administrator for this system. For InstallShield users, Object Design recommends that you use the InstallShield IS (USER_ADMINISTRATOR) call instead. Some installation processes, especially those involving the registry, might not be possible if the user is not running as administrator.


Return	TRUE if the user is administrator, FALSE otherwise.

OS_NeedCheckpoint

EXPORT int OS_NeedCheckpoint ()

Determines if a Server log file or a RAWFS partition exists on the system. If they do, the user should be queried to see if they need to run checkpoint before proceeding.


Return	TRUE if a checkpoint might be needed, FALSE otherwise.

OS_NeedCheckpoint examines the registry under

HKEY_LOCAL_MACHINE\SOFTWARE\Object Design Inc.\ObjectStore.4.0\Server

and looks for either a Log File entry or a Partition0 entry. It does not check to see if either of these entries corresponds to actual data on the system.

OS_OStoreInstalled

EXPORT int OS_OStoreInstalled (CHAR *pOSRootDir, CHAR *pSingleDir, CHAR *pExamplesDir,
        CHAR *pHTMLDir, CHAR *pPScriptDir)

Attempts to determine if ObjectStore is currently installed on the system. If it is, it attempts to determine pathnames for directories being used. This entry should be called very early in the setup process. All the directories involved are obtained from the corresponding registry entries found in pOSRootDir, which points to a 512-byte buffer that holds the current OS_ROOTDIR.


pSingleDir	Points to a 512-byte buffer that holds the current single directory (the directory binsngl).
pExamplesDir	Points to a 512-byte buffer that holds the current examples directory (the directory above examples).
pHTMLDir	Points to a 512-byte buffer that holds the current HTML documentation directory (the directory above doc).
pPScriptDir	Points to a 512-byte buffer that holds the current PostScript documentation directory (the directory above doc\pscript).
Return	Additive combinations of 1: If the OS_ROOTDIR directory is found 2: If the Single directory is found 4: If the Examples directory is found 8: If the HTML documentation directory is found 16: If the PostScript documentation directory is found

Each of the return values depends on the corresponding directory's being named in the registry data and on the existence of the named directory in the system.

An internal default installation directory pathname might be set based on what directories are found. At any given time, only one installation directory is permitted; therefore, if multiple directories are encountered, the internal setting corresponding to the lower return value (that is, OS_ROOTDIR is preferred) is used.

OS_OStoreRunning

EXPORT BOOL OS_OStoreRunning ()

Attempts to determine if ObjectStore is currently running. Looks for any services (Server or Cache Manager) that might be running and for ObjectStore DLLs that might be active.


Return	TRUE if it appears that ObjectStore is running, FALSE otherwise.

OS_rename_dir

EXPORT BOOL OS_rename_dir (char *Path, char *NewPath)

Renames a directory (or file).


Path	Original name of file or directory.
NewPath	New name.
Return	TRUE if the rename succeeds, FALSE otherwise.

OS_RenameToLongFiles

EXPORT BOOL OS_RenameToLongFiles (char *InstallDir)

Renames files to their correct long (non-8.3) names.


InstallDir	OS_ROOTDIR of where files have been installed.
Return	Always returns TRUE.

OS_SetInstallDirectories

EXPORT int OS_SetInstallDirectories (CHAR *pOSRootDir, CHAR *pSingleDir,
                  CHAR *pExamplesDir, CHAR *pHTMLDir,
                  CHAR *pPScriptDir)

Sets registry values corresponding to the directory names passed in. All names passed in should be the same, but directories corresponding to components that have not been installed should be set to "". Do not pass in NULL pointers.


pOSRootDir	Points to OS_ROOTDIR value.
pSingleDir	Points to path of parent of binsngl directory.
pExamplesDir	Points to path of parent of examples directory.
pHTMLDir	Points to path of parent of doc directory.
pPScriptDir	Points to path of parent of doc\pscript directory.
Return	Always returns 0.

OS_SetRegistration

EXPORT int OS_SetRegistration (CHAR *pRegisterType, CHAR *pRegEntry, int LocalMachBool)

Sets the ObjectStore registration registry information.


pRegisterType	Specific key value to be set.
pRegEntry	Pointer value string.
LocalMachBool	If 1, the value is set in HKEY_LOCAL_MACHINE; otherwise, the value is set in HKEY_CURRENT_USER.
Return	Always returns 1.

See OS_GetRegistration for details of registration keys used by ObjectStore.

OS_SetServerParameter

EXPORT int OS_SetServerParameter (const CHAR *Key, CHAR *Value)

Sets an ObjectStore Server parameter value.


Key	Points to the parameter name.
Value	Points to the new value.
Return	0 if the parameter is known, -1 otherwise.

Server parameters are stored under the registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Object Design Inc.\ObjectStore.4.0\Server

OS_SetServerParams

EXPORT int OS_SetServerParams ()

Runs the ObjectStore Server Parameters dialog and sets any parameters selected by the user.


Return	0 if the user selected Cancel, 1 if the user selected OK.

OS_SetupRawfs

EXPORT int OS_SetupRawfs (int *bPartChanged)

Runs the ObjectStore RAWFS partition dialogs and sets registry values appropriately.


bPartChanged	When the dialog returns, the installation checks to see if the partitions have changed. If so, the utility ORs a changed bit into the int pointed to by this argument.
Return	0 if the user selected Cancel, 1 if the user selected OK.

OS_ShutdownOStore

EXPORT int OS_ShutdownOStore ()

Attempts to shut down any running ObjectStore services (Server or Cache Manager).


Return	TRUE if all processes appear to have been stopped, FALSE otherwise.

OS_status_update_bar_num

EXPORT int OS_status_update_bar_num (char *CurrFile)

Gets the total disk space used by files installed to this point.


CurrFile	OS_ROOTDIR-relative name of the next file to be installed.
Return	Number of bytes installed before curr_file.

OS_TermDLL

EXPORT int OS_TermDLL () 

Terminate DLL

Frees resources after execution. The last DLL entry called.


Return

Always returns 0.

OS_Uninstall

EXPORT int OS_Uninstall (char *OSRootDir, BOOL bUninstallRAWFS)

Removes ObjectStore from the system; attempts to remove all vestiges of ObjectStore.


OSRootDir	Current OS_ROOTDIR value.
bUninstallRAWFS	TRUE to remove RAWFS files in addition to ObjectStore executables.
Return	Always returns TRUE.

OS_update_environment

EXPORT BOOL OS_update_environment (char *OSRootDir, BOOL bRuntimeOnly, char 
*OSSchemaDir)

Sets various environment values.


OSRootDir	Pointer to OS_ROOTDIR value.
bRuntimeOnly	TRUE if this installation does not include development support.
OSSchemaDir	Pointer to a schema directory, if this is a client-only development installation.
Return	TRUE if the environment was modified, FALSE otherwise.

Environment values that can be set or modified by this call include

OS_ROOTDIR

Always set.

OS_LIBDIR

Set if OSSchemaDir is nonnull.

OS_TMPDIR

Always set.

PATH

Always set.

INCLUDE

Set if bRuntimeOnly is FALSE

LIB

Set if bRuntimeOnly is FALSE

For Windows NT, settings are made in the registry. For Windows 95, settings are made in OS_AUTO.BAT, which is called from AUTOEXEC.BAT.

OS_UpdateStartup

EXPORT int OS_UpdateStartup (BOOL StartServer, CHAR *InstallDir, BOOL StartNow)

Updates Server autostartup values in the registry and in system services databases.


StartServer	TRUE to have Server start automatically, FALSE otherwise.
InstallDir	Pointer to OS_ROOTDIR string.
StartNow	TRUE if user should be queried about starting the Server immediately (assuming that StartServer is also TRUE), FALSE to skip the query and delay starting the Server. It might be appropriate to delay startup if some elements of the installation (notably MSVCRT.DLL) are not to be installed until after the system reboots.
Return	Always returns 0.

OS_UnzipOneFile

EXPORT INT OS_UnzipOneFile (char *UnzipName)

Unzips one file.


UnzipName	Name of the file to be extracted from the current zip file.
Return	Return 0 if no errors are encountered, nonzero otherwise.

Unzip error codes are defined in os_setup.h, with names beginning with PK_ and values ranging from 1 to 51.

OS_ZipLogFiles

EXPORT BOOL OS_ZipLogFiles (char *InstallDir)

Opens log files OSUNZIP.LOG and OSUNZIP.ERR in InstallDir and redirects stdout and stderr to those files. You can use this entry to direct unzip output to these files, but the InstallShield installation does not currently do this.


InstallDir	Directory into which the log files will be placed.
Return	Currently always returns 1.

[previous] [next]

Updated: 03/26/98 21:57:32

Terminate DLL	Frees resources after execution. The last DLL entry called.
Return	Always returns 0.

OS_ROOTDIR	Always set.
OS_LIBDIR	Set if OSSchemaDir is nonnull.
OS_TMPDIR	Always set.
PATH	Always set.
INCLUDE	Set if bRuntimeOnly is FALSE
LIB	Set if bRuntimeOnly is FALSE