The information about the database utility APIs is organized in the following manner:
The os_dbutil class
All the functions in this facility are members of the class os_dbutil. See os_dbutil in Chapter 2, Class Library, of the ObjectStore C++ API Reference for a complete description of the os_dbutil class.
Initializing the database utility API
Call the following function before using any other members of os_dbutil:
static void os_dbutil::initialize() ;You only need to call this function once in each application.
static void disk_free(
const char *hostname,
os_free_blocks *blocks
) ;
| os_unsigned_int32 | struct_version; |
| os_unsigned_int32 | free_blocks; |
| os_unsigned_int32 | file_system_size; |
| os_unsigned_int32 | used_blocks; |
disk_free() sets the values of these data members for the instance of os_free_blocks pointed to by the argument blocks.
See also
static void svr_stat(
const char *server_host,
os_unsigned_int32 request_bits
os_svr_stat *svrstat_data
) ;
For each of the classes described below, the constructor sets struct_version to the value of os_free_blocks_version in the dbutil.hh file included by your application. If this version is different from that used by the library, err_misc is signaled. The constructor initializes all other members to 0.
Public data members in os_svr_stat_svr_header
The os_svr_stat_svr_header data member (a member of os_svr_stat) has the following public data members:
| os_unsigned_int32 | struct_version; |
| char* | os_release_name; |
| os_unsigned_int32 | server_major_version; |
| os_unsigned_int32 | server_minor_version; |
| char* | compilation; |
Public data members in os_svr_stat_svr_parameters
The os_svr_stat_svr_parameters data member (a member of os_svr_stat) has the following public data members:
Public data members in os_svr_stat_svr_rusage
The os_svr_stat_svr_rusage data member (a member of os_svr_stat) has the following public data members:
Public data members in os_svr_stat_svr_meters
The os_svr_stat_svr_meters data member (a member of os_svr_stat) has the following public data members:
Public data members in os_svr_stat_client_info
The os_svr_stat_client_info data member (a member of os_svr_stat) has the following public data members:
| os_unsigned_int32 | struct_version; |
| os_svr_stat_client_process* | process; |
| os_svr_stat_client_state* | state; |
| os_svr_stat_client_meters* | meters; |
os_db_util::os_svr_stat() allocates instances of these as required. They are automatically cleaned up when the os_svr_stat instance (as provided by the caller) is deleted.
Public data members in os_svr_stat_client_process
The os_svr_stat_client_process data member (a member of os_svr_stat_client_info) has the following public data members:
| os_unsigned_int32 | struct_version; |
| char* | host_name; |
| os_unsigned_int32 | process_id; |
| char* | client_name; |
| os_unsigned_int32 | client_id; |
Public data members in os_svr_stat_client_state
The os_svr_stat_client_state data member (a member of os_svr_stat_client_info) has the following public data members:
enum os_client_lock_type {
OSSVRSTAT_CLIENT_LOCK_TO_MAX_BLOCKS,
OSSVRSTAT_CLIENT_LOCK_TO_NBLOCKS,
};
enum os_client_state_type {
OSSVRSTAT_CLIENT_WAITING_MESSAGE,
OSSVRSTAT_CLIENT_EXECUTING_MESSAGE,
OSSVRSTAT_CLIENT_WAITING_RANGE_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_RANGE_WRITE_LOCK,
OSSVRSTAT_CLIENT_WAITING_SEGMENT_WRITE_LOCK,
OSSVRSTAT_CLIENT_DEAD,
OSSVRSTAT_CLIENT_WAITING_SEGMENT_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_DB_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_DB_WRITE_LOCK,
};
Data in locking_start_sector and locking_for_n_sectors is valid only when lock_state is OSSVRSTAT_CLIENT_STATE_WAITING_RANGE_READ_LOCK or OSSVRSTAT_CLIENT_STATE_WAITING_RANGE_WRITE_LOCK.
Determining Sector Size with get_sector_size()
static os_unsigned_int32 get_sector_size() ;
static os_boolean svr_client_kill(
const char *server_host,
os_int32 client_pid,
const char *client_name,
const char *client_hostname,
os_boolean all,
os_int32 &status
) ;
client_pid is the process ID of the client to kill. client_name is the name of the client to kill. client_hostname is the name of the machine running the client to kill.
If all is 1, the other arguments except server_host are ignored, and all clients on the specified Server are killed.
status is set to -2 if a client was killed, 0 if no clients matched the specifications, 2 if multiple clients matched the specification. Any other value means that access was denied.
static char *svr_ping(
const char *server_host,
os_svr_ping_state &state
) ;
static os_boolean svr_shutdown(
const char *server_host
) ;
static os_boolean svr_checkpoint(
const char *hostname
) ;
static void set_client_name (const char *name) ;Sets the client name string for message printing.
static char const* get_client_name();
static void close_server_connection(const char *hostname);Closes the connection the application has to the ObjectStore Server running on the machine named hostname.
static void close_all_server_connections();Closes all connections the application has to ObjectStore Servers.
static void cmgr_stat(
const char *hostname,
os_int32 cm_version_number,
os_cmgr_stat *cmstat_data
) ;
The constructor sets struct_version to the value of os_free_blocks_version in the dbutil.hh file included by your application. If this version is different from that used by the library, err_misc is signaled. The constructor initializes all other members to 0.
Public data members in os_cmgr_stat_client
The os_cmgr_stat_client data member (a member of os_cmgr_stat) has the following public data members:
| os_unsigned_int32 | struct_version; |
| os_int32 | pid; |
| os_unsigned_int32 | euid; |
| char* | name; |
| os_int32 | major_version; |
| os_int32 | minor_version; |
| os_int32 | commseg; |
Public data members in os_cmgr_stat_svr
The os_cmgr_stat_svr data member (a member of os_cmgr_stat) has the following public data members:
| os_unsigned_int32 | struct_version; |
| char* | host_name; |
| os_int32 | client_pid; |
| char* | status_str; |
Public data members in os_cmgr_stat_file_usage
The os_cmgr_stat_file_usage data member (a member of os_cmgr_stat) has the following public data members:
| os_unsigned_int32 | struct_version; |
| char* | file_name; |
| os_unsigned_int32 | file_length; |
| os_boolean | is_free; |
Deleting Unused Cache and commseg Files with cmgr_remove_file()
static char *cmgr_remove_file(
const char *hostname,
os_int32 cm_version_number
) ;
static char *cmgr_shutdown(
const char *hostname,
os_int32 cm_version_number
) ;
static void chgrp(
const char *pathname,
const char *gname
) ;
Changes the primary group of the rawfs directory or database whose name is pathname. gname is the name of the new group.
static void chown(
const char *pathname,
const char *uname
) ;
static void chmod(
const char *pathname,
const os_unsigned_int32 mode
) ;
static void rehost_link(
const char *pathname,
const char *new_host
) ;
static void rehost_all_links(
const char *server_host,
const char *old_host,
const char *new_host
) ;
static os_boolean copy_database(
const char *src_database_name,
const char *dest_database_name
) ;
static char **expand_global(
char const *glob_path,
os_unsigned_int32 &n_entries
) ;
static void mkdir(
const char *path,
const os_unsigned_int32 mode,
os_boolean create_missing_dirs = 0
) ;
static void make_link(
const char *target_name,
const char *link_name
) ;
A rawfs can have symbolic links pointing within itself or to another Server's rawfs. The Server follows symbolic links within its rawfs for all os_dbutil members that pass pathname arguments, unless specified otherwise by a function's description; only os_dbutil::stat() can override this behavior. All members passing pathname arguments also follow cross-server links on the application side, unless specified otherwise by a function's description.
To access a particular database or directory, a client can follow as many as 15 cross-Server links. For example, a client traverses a link to Server Q. Server Q sends the client to Server P. Server P sends the client to another Server or even back to Server Q. Each connection to a Server counts as one link. It does not matter whether or not the Server was previously connected to in the link chain. When the client reaches the sixteenth link, ObjectStore displays the error message err_too_many_cross_svr_links.
To access a particular database or directory in its rawfs, the Server can traverse as many as 10 (same-Server) links. When the Server reaches the eleventh link, ObjectStore displays the error message err_too_many_links.
In a chain of links, a client can return to a Server that it contacted earlier in the chain. In this situation, the Server's count of links within its rawfs begins with one. It does not continue the count from where it left off during the previous connection. Each time a link sends the client to a Server, the Server can follow as many as ten links within its rawfs.
These limits allow ObjectStore to catch circular links. For example, A is a link to B, and B is either directly or indirectly a link to A.
A rawfs symbolic link always has the ownership and the permissions of the parent directory.
static void remove(char const *path) ;
static void rmdir(const char *path) ;
static void rename(
const char *source,
const char *target
) ;
static os_rawfs_entry *stat(
const char *path,
const os_boolean b_chase_links = 1
) ;
static os_rawfs_entry **list_directory(
const char *path,
os_unsigned_int32 &n_entries
) ;
static os_int32 ossize(
const char *pathname,
const os_size_options *options
) ;
The constructor sets struct_version to the value of os_size_options_version in the dbutil.hh file included by your application. If this version is different from that used by the library, err_misc is signaled. The constructor initializes all other members to 0.
See also
static os_unsigned_int32 osverifydb(
const char *dbname,
os_verify_db_options* opt= 0
) ;
os_boolean verify_segment_zero ;
/* verify the schema segment */
os_boolean verify_collections ;
/* check all top-level collections */
os_boolean verify_pointer_verbose;
/* print pointers as they are verified */
os_boolean verify_object_verbose ;
/* print objects as they are verified */
os_boolean verify_references ;
/* check all OS references */
os_int32 segment_error_limit ;
/* maximum errors per segment */
os_boolean print_tag_on_errors ;
/* print out the tag value on error */
const char* explicit_workspace
/* The workspace name if one was explicitly specified. */
const void* track_object_ptr ;
/* Track object identified by pointer */
const char* track_object_ref_string;
/* Track the object identified by the reference string. */
enum {
default_action,
ask_action,
null_action,
} illegal_pointer_action ;
You must have called os_collection::initialize() and os_mop::initialize() prior to calling this function.If OS__DBUTIL_NO_MVCC is set, this function opens the database for read only, rather than multiversion concurrency control (the default).
static os_boolean compare_schemas(
const os_database* db1,
const os_database* db2,
os_boolean verbose = 1
) ;
If verbose is nonzero, the function issues a message to the default output describing any incompatibility.
static char *set_application_schema_path(
const char *executable_pathname,
const char *database_pathname
) ;
err_misc: An unexpected 0 argument or an invalid pathname was passed; version mismatch of an in/out structure argument.
err_rpc: RPC error.
err_too_many_cross_svr_links: Excessively long cross-server link chain. The maximum depth of a cross-server link chain is currently 15.
err_no_rawfs: There is no database file system (rawfs) on this Server.
err_read_only_file_system: The file database is stored in a read-only file system.
err_no_credentials: Access is not permitted; no credentials were presented.
err_server_not_superuser: The Server is not running as the superuser.
err_link_not_found: Intrarawfs link was not found.
err_too_many_links: Too many levels of intrarawfs links.
err_rawfs_not_upgraded: The rawfs is from an old release.
err_permission_denied: Permission to access this database was denied.
err_invalid_pathname: The rawfs pathname is not valid.
err_directory_not_found: The directory was not found.
err_database_not_found: The rawfs database was not found.
err_link_not_found: The rawfs link was not found.
Updated: 03/31/98 15:43:20