ydb_env_set respects existing $ydb_gbldir & $ydb_routines and creates YDBOCTO & YDBAIM regions if they don't exist
Final Release Note
Enhancements to ydb_env_set
make it friendlier to existing environments.
-
Sourcing
ydb_env_set
respects existing values ofydb_gbldir
andydb_routines
, and adjusts$ydb_routines
to point tolibyottadbutil.so
of the current YottaDB release, in the parent directory or the UTF-8 subdirectory, depending on the desired mode. Previously, it replaced those values with standard values pointing to an environment under$ydb_dir
, defaulting to$HOME/.yottadb
if not defined. As before, sourcingydb_env_unset
restores the prior values. Enhancements include:-
ydb_routines
now automatically includes the plugins in the$ydb_dist/plugin
directory. Environment variables to call exported C routines in plugins are also created. -
In the event the environment is coming up after an unclean shutdown, it recovers the environment using the existing
$ydb_gbldir
using MUPIP JOURNAL RECOVER or MUPIP JOURNAL ROLLBACK depending on the replication setting. Note that existing regions must have before-image journaling enabled, and the YDBAIM region is deleted, since it is automatically created on demand. -
Global directory files are automatically upgraded to the format of the current YottaDB release.
-
If YDBOCTO and YDBAIM regions do not exist in the global directory, it creates them. The database and journal file for the YDBOCTO region are created in the same directories as the database and journal files of the DEFAULT region, with the same journal settings as the DEFAULT region's database file. Since YDBAIM is an AutoDB region, the database file is not created, but when created on demand, it will be created in the same directory as the DEFAULT region.
-
-
If
ydb_chset
is not set, inference of M vs. UTF-8 mode is more reliable than it was previously. We recommend settingydb_chset
to the preferred mode instead of havingydb_env_set
infer it. -
Sourcing
ydb_env_set
sets$?
, whereas previously it did not:- 0 is normal exit, as expected
- 1 means that
$ydb_dist
does not match the location ofydb_env_set
- 2 means that
$gtm_dist
does not match the location ofydb_env_set
- 3 means that neither
$ydb_dist
nor$gtm_dist
match the location ofydb_env_set
- Other non-zero error codes are as returned by running
set^%YDBENV
Note that:
-
While
ydb_env_set
attempts to be more user-friendly, it assumes well-configured environment, and misconfigured environments (for example a$ydb_routines
of$ydb_dist/libyottadbutil.so $ydb_dist/utf8/libyottadbutil.so
) can make it misbehave: the$ydb_dist/utf8/libyottadbutil.so
will makeydb_env_set
infer a UTF-8 environment, however the prior$ydb_dist/libyottadbutil.so
means that YottaDB will find M mode object code for utility routines. -
If upgrading from an older release of YottaDB, the environment must be cleanly shut down with the prior release.
-
Although upgrading and using GT.M environments should work, this has not been tested.
Description
Sourcing ydb_env_set
was designed to provide new users with a robust “out of box” experience, including crash recovery and journal file management. While it does that, it would be helpful to extend its crash recovery and journal file management to existing environments. Also, while doing this, it would be helpful to create YDBOCTO and YDBAIM regions if they don't exist.
This is being labeled a YottaDB r1.34 Issue. However, since some research is required to see what is feasible (since an existing environment may or may not be well suited to automated crash recovery and journal file management), in the event it proves to be problematic, it can be deferred to r1.36 or later.
Draft Release Note
Sourcing ydb_env_set
extends its crash recovery and journal file management to existing environments. It also creates YDBAIM and YDBOCTO regions with reasonable defaults, if they don't already exist.