This is part II of the article, see Part I here

The global_parameters file

Here is an example of this file: dbi services.

Besides the location of the software packages and installation directory, this mandatory sourceable bash file contains all the settings required to create a seed docbase and any instantiation of it. Those settings have the following syntax:

stem_parameter-name=value

e.g.:
DCTM0_DOCBASE=seed
DCTM0_DOCBASE_ID=1
DCTM0_SERVICE_NAME=${DCTM0_DOCBASE}
DCTM0_SERVICE_PORT=50000
DCTM0_RDBMS=oracle
DCTM0_DATABASE_OWNER=${DCTM0_DOCBASE}
DCTM0_DATABASE_PASSWORD=${DCTM0_DOCBASE}
[[ ${DCTM0_RDBMS} == "postgres" ]] && DCTM0_DB_SERVER_PORT=5432
DCTM0_ROOT=${dctm_root}/${DCTM0_DOCBASE}
DCTM0_HOST=cs1
DCTM0_INSTALL_OWNER=${dctm_owner}
DCTM0_INSTALL_PASSWORD=${DCTM0_INSTALL_OWNER}
DCTM0_DOCBROKER_NAME=docbroker
DCTM0_DOCBROKER_PORT=1489
DCTM0_SERVER_HTTP_PORT=9080
DCTM0_SERVER_HTTP_MEMORY="-Xms512m -Xmx512m"

Here, a docbase named seed is defined with an id of 1, a TCP/IP port of 50000, etc. Its stem is DCTM0. Although it may look overly complicated, this prefix trick allows to define several docbases at once in global_parameters without parameter name clash since the prefix, or stem, make them unique. This way, a history of the docbases can also be kept in the same file. However, it is mostly useful in that it allows to create or instantiate several docbases at the same time, see later for more about this. For the curious ones, the stem idea comes from the Rexx programming language where stems are used to implement multi-dimensional arrays, trees, lists, records, etc., an original take on data structure syntax.

Of course, these indirections must be resolved to access the values; this is done in function global_parameter.set_role() by using bash’s dereferencing syntax, e.g.:

local tmp=${stem}_DOCBASE_ID; tmp=${!tmp}
echo "${title} docbase id is : ${tmp}"

On line 1, the name of the variable of interest is computed, e.g. DCTM10_DOCBASE_ID for ${stem} set to DCTM10; next, this variable name is dereferenced (or expanded in bash’s parlance) into ${tmp} using the ${!var} notation.

At any one time, we only need to know the docbase to be created or the seed docbase and the docbase to be instantiated into. Their respective settings will be stored in the variables ${ACTIVE_*} and ${SEED_*} after expansion.

global_parameters takes up to 2 parameters when invoked:

Usage
. global_parameters [seed_repo [new_repo]]

where:
seed_repo is the stem of the repository to be created or used as a seed;
it defaults to DCTM0 and is used in create_docbase.sh and instantiate_docbase.sh.
for creation, it points to the specs of the docbase to be created and that can be used later as a seed;
for instantiation, seed_repo is the stem of the repository to be taken as the seed during the instantiation and new_repo is the one of the docbase to instantiate.
all repositories must have their specs defined in this global_parameters file.

global_parameters is usually invoked by the scripts create_docbase.sh and instantiate_docbase.sh with the same command-line parameters they receive. There is no real need to invoke it directly since a tailored environment for each repository after its instantiation can be set using the more adequate function swr() (standing for SWitch Repository) defined in dmadmin’s ~/.profile by create_docbase.sh, more on this later. This also prevents polluting the environment with the settings of all the docbases defined in there. However, being a bash file, it also allows to define several useful functions:

function show_repo() stem [title]
function show_seed()
function show_active()
function set_role() (SEED | ACTIVE) stem

show_repo() stem [title] displays the parameters of the repository as dereferenced from the given stem, with title as explanatory string, which may be empty. E.g.:

$ show_repo DCTM10 "stem DCTM10 defines:"
stem DCTM10 defines: docbase name is : repo10
stem DCTM10 defines: docbase id is : 100011
stem DCTM10 defines: docbase service name is : repo10
stem DCTM10 defines: docbase service port is : 50100
stem DCTM10 defines: docbase host is : cs2
stem DCTM10 defines: docbase root directory is : /u01/dctm/repo10
stem DCTM10 defines: docbase owner is : dmadmin
stem DCTM10 defines: installer password is : dmadmin
stem DCTM10 defines: docbase docbroker name : docbrokerrepo010
stem DCTM10 defines: docbase docbroker port : 1507
stem DCTM10 defines: RDBMS is : postgres
stem DCTM10 defines: database owner is : repo10
stem DCTM10 defines: database password is : repo10
stem DCTM10 defines: database server port is : 5500
stem DCTM10 defines: docbase http server port : 9760
stem DCTM10 defines: docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

$ show_repo DCTM1
docbase name is : repo01
docbase id is : 10001
docbase service name is : repo01
docbase service port is : 50010
docbase host is : cs2
docbase root directory is : /u01/dctm/repo01
docbase owner is : dmadmin
installer password is : dmadmin
docbase docbroker name : docbroker
docbase docbroker port : 1489
RDBMS is : oracle
database owner is : repo01
database password is : repo01
database server port is : N/A
docbase http server port : 9180
docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

show_repo() can be manually invoked to verify the repository settings before they are used by create_docbase.sh and instantiate_docbase.sh.

In addition to the defined stems, the roles SEED and ACTIVE are considered stems too but are set dynamically by set_role(). Thus:

$ set_role SEED DCTM1
SEED docbase name is : repo01
SEED docbase id is : 10001
SEED docbase service name is : repo01
SEED docbase service port is : 50010
SEED docbase host is : cs2
SEED docbase root directory is : /u01/dctm/repo01
SEED docbase owner is : dmadmin
SEED installer password is : dmadmin
SEED docbase docbroker name : docbroker
SEED docbase docbroker port : 1489
SEED RDBMS is : oracle
SEED database owner is : repo01
SEED database password is : repo01
SEED database server port is : N/A
SEED docbase http server port : 9180
SEED docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

$ show_repo SEED Seed
Seed docbase name is : repo01
Seed docbase id is : 10001
Seed docbase service name is : repo01
Seed docbase service port is : 50010
Seed docbase host is : cs2
Seed docbase root directory is : /u01/dctm/repo01
Seed docbase owner is : dmadmin
Seed installer password is : dmadmin
Seed docbase docbroker name : docbroker
Seed docbase docbroker port : 1489
Seed RDBMS is : oracle
Seed database owner is : repo01
Seed database password is : repo01
Seed database server port is : N/A
Seed docbase http server port : 9180
Seed docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

$ set_role ACTIVE DCTM10
ACTIVE docbase name is : repo10
ACTIVE docbase id is : 100011
ACTIVE docbase service name is : repo10
ACTIVE docbase service port is : 50100
ACTIVE docbase host is : cs2
ACTIVE docbase root directory is : /u01/dctm/repo10
ACTIVE docbase owner is : dmadmin
ACTIVE installer password is : dmadmin
ACTIVE docbase docbroker name : docbrokerrepo010
ACTIVE docbase docbroker port : 1507
ACTIVE RDBMS is : postgres
ACTIVE database owner is : repo10
ACTIVE database password is : repo10
ACTIVE database server port is : 5500
ACTIVE docbase http server port : 9760
ACTIVE docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

$ show_repo ACTIVE Active
Active docbase name is : repo10
Active docbase id is : 100011
Active docbase service name is : repo10
Active docbase service port is : 50100
Active docbase host is : cs2
Active docbase root directory is : /u01/dctm/repo10
Active docbase owner is : dmadmin
Active installer password is : dmadmin
Active docbase docbroker name : docbrokerrepo010
Active docbase docbroker port : 1507
Active RDBMS is : postgres
Active database owner is : repo10
Active database password is : repo10
Active database server port is : 5500
Active docbase http server port : 9760
Active docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

# same effect with:
$ . global_parameters DCTM1 DCTM10
SEED docbase name is : repo01
SEED docbase id is : 10001
SEED docbase service name is : repo01
SEED docbase service port is : 50010
SEED docbase host is : cs2
SEED docbase root directory is : /u01/dctm/repo01
SEED docbase owner is : dmadmin
SEED installer password is : dmadmin
SEED docbase docbroker name : docbroker
SEED docbase docbroker port : 1489
SEED RDBMS is : oracle
SEED database owner is : repo01
SEED database password is : repo01
SEED database server port is : N/A
SEED docbase http server port : 9180
SEED docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

ACTIVE docbase name is : repo10
ACTIVE docbase id is : 100011
ACTIVE docbase service name is : repo10
ACTIVE docbase service port is : 50100
ACTIVE docbase host is : cs2
ACTIVE docbase root directory is : /u01/dctm/repo10
ACTIVE docbase owner is : dmadmin
ACTIVE installer password is : dmadmin
ACTIVE docbase docbroker name : docbrokerrepo010
ACTIVE docbase docbroker port : 1507
ACTIVE RDBMS is : postgres
ACTIVE database owner is : repo10
ACTIVE database password is : repo10
ACTIVE database server port is : 5500
ACTIVE docbase http server port : 9760
ACTIVE docbase http server memory : -Xms512m -Xmx1024m
Scripts'dir is /mnt/shared/blog-seed-docbase

set_role() is invoked by global_parameters with the following logic:

  • when global_parameters is invoked with one or no parameter, the repository the stem (or DCTM0 if no stem was given) resolves into receives the ACTIVE role;
  • when 2 stems are passed as parameters, the docbase the first stem resolves into receives the SEED role, and the one the second stem resolves into receives the ACTIVE role;

Obviously, the SEED role is only used in the script instantiate_docbase.sh and refers to the model docbase. The ACTIVE role is used in both scripts to refer to the docbase to be created or instantiated.

Several settings relate to the supported RDBMS, Oracle or PostgreSQL:

if [[ "${ACTIVE_RDBMS}" == "oracle" ]]; then
   cs_package=documentum_server_22.4_linux64_oracle.tar
   oracle_download_url=https://download.oracle.com/otn_software/linux/instantclient/217000
   oracle_ic_basic=instantclient-basic-linux.x64-21.7.0.0.0dbru.zip
   oracle_ic_sqlplus=instantclient-sqlplus-linux.x64-21.7.0.0.0dbru.zip
   db_server_host_account=oracle
   db_server_host_password=${db_server_host_account}
   db_server_host_alias=db
   db_server_host_ip_address=192.168.0.21
   db_listener_port=1521
   # although distinct concepts, the connect string and the service name must be equal to satisfy the migration utility;
   db_connect_string=pdb1
   db_service_name=pdb1
   db_sys_account=sys
   db_sys_password=${db_sys_account}
   db_datafile_root=/u02/oradata/ORCL/${db_service_name}
   db_remote_connect_string=orcl
elif [[ "${ACTIVE_RDBMS}" == "postgres" ]]; then
   cs_package=documentum_server_22.4_linux64_postgres.tar
   postgresql_download_url=https://ftp.postgresql.org/pub/source
   jdbc_postgresql_download_url=https://jdbc.postgresql.org/download
   postgresql_custom_package=postgresql-15.1.tar.gz
   # set this to yes or no if a compilation is needed to produce the custom package;
   postgresql_compile=no
   postgresql_jdbc_package=postgresql-42.5.1.jar
   db_server_host_alias=localhost
   db_connect_string=${ACTIVE_DOCBASE}
else
   echo "Invalid or Unsupported RDBMS [${ACTIVE_RDBMS}]"
  rc=1
fi

The packages to download and their URLs are specified there. For the Oracle RDBMS, we will use the InstantClient and SQL*Plus. The InstantClient includes the JDBC drivers required by the Migration Utility. For the PostgreSQL RDBMS, we download the source package and the latest JDBC drivers from the global_properties.${*postgresql_download_url} locations.

For Oracle, we need to connect to the host to perform some tasks, e.g. schema export and import, cleanup; thus, we need the host’s IP address and account. For PostgreSQL, this is not needed as the database is always local (embedded). For Oracle, we also need the sys credentials to manage accounts in the existing database. If this is delegating too much power, especially if the database is shared among several unrelated applications, the database accounts need to be created in advance and the scripts be adapted consequently. When using Oracle RDBMS, a database exclusively dedicated to the instantiated repositories and shared among them is the ideal situation. In this context, a full access to the sys account is justified but this may depend on your organization. Evidently, open-source, free software offers much more flexibility in this regard.

Finally, we declare the name of the connect string to use to connect to the database; for Oracle, it will be the SQL*Net alias that will be defined in the tnsnames.ora file; for PostgreSQL, it will be the name of the INI section that will be defined in dmadmin‘s ~/.odbc.ini file since the database is accessed through the ODBC API. More on these parameters in the paragraph dedicated to the database.

A trendy alternative to this parameter=value file format could be json or yaml files, with an intermediate conversion to bash syntax using the parsing tools jq and yq. Another excellent alternative would consist in storing each docbase’s settings in its own file and provide the file(s) to source as command-line arguments. That would allow to not use the stem trick if found too complicated. There are many ways to jungle between different sets of configurations but the stem one is quite a simple and easy one to use as it is pure, executable bash and therefore does not need any intermediate translation; moreover, it centralizes into one unique file all the docbase definitions to be used. Adapt as you see fit.

See Part III here

Post Views: 1,748
Thumbnail [60x60]
by
Cesare Cervini