Defining an Env Descriptor

Zero or more Env descriptors can immediately follow the InfoHub descriptor, or start the configuration definition if the InfoHub descriptor is implicit; and zero or more Env descriptors can immediately follow any Publisher descriptor. Those in the first location define common environment variables for all processes used by the InfoHub; those in the second location define common environment variables for all PipeLine generated processes subject to that Publisher. The syntax of an Env Descriptor is:

Env:EnvVarName[=[Value]][,,,,]

If the configuration processing encounters an Env descriptor that does not follow the InfoHub descriptor or a Publisher descriptor, it produces an IHENVPLACE error. There are three types of Env descriptora??one sets values in the environment of InfoHub processes, another with an equal-sign but no value ensures environment variables are not set (that is, cleared), and a third to invoke a shell script that manages the target environment. For example:

The InfoHub may itself use an encrypted database. Blocking its obfuscated password in $gtm_passwd from other processes (such as PIPE processes in PipeLine descriptors, which do not need to access its database) is accomplished with an Env:gtmpasswd= descriptor (with an equal-sign, but no value) after the InfoHub descriptor.
A Publisher that gathers information from an application deployed on a different version of GT.M than the InfoHub (or with a global directory that uses relative paths to its database files and/or refers to environment variables) needs to have the appropriate environment variables set. If the InfoHub has only read access to the database, ensure that the gtm_tmp and gtm_log environment variables are appropriately set. Note: gtm_log is not used starting with GT.M V6.0-000. If the environment variable IHCD exists, the Pipeline sets its working directory to the value of IHCD. For example, when a global directory uses relative paths: IHCD is set to the base of the relative paths. A set of Env descriptor lines may look like:
and provides the needed environment variables after the Publisher descriptor for PipeLine information gathering by that Publisher.
If an application provides a script that can be sourced to set up environment variables, Env:/path/to/script, can be used in lieu of setting them individually. Since this will overwrite the gtmroutines environment variable, please add the paths for the InfoHub back in using an ENV descriptor for gtmroutines environment variable. For example,
Env:/path/to/envscript.sh
Env:gtmroutines="$gtmroutines /path/to/infohub /path/to/infohub/pipecommands /path/toinfohub/plugins /path/to/gtmposixplugin "
If applications that run in both UTF-8 and M mode are involved, please adjust the gtmroutines enviroment variable descriptor accordingly. For example, for the applications using M mode:"
Env:gtmroutines="$gtmroutines /path/to/infohub/M(/path/to/infohub) /path/to/infohub/pipecommands/M(/path/to/infohub/pipecommands) /path/toinfohub/plugins/M(/path/toinfohub/plugins) /path/to/gtmposixplugin/M(/path/to/gtmposixplugin)"
and for the applications using UTF-8 mode:
Env:gtmroutines="$gtmroutines /path/to/infohub/UTF8(/path/to/infohub) /path/to/infohub/pipecommands/UTF8(/path/to/infohub/pipecommands) /path/toinfohub/plugins/UTF8(/path/toinfohub/plugins) /path/to/gtmposixplugin/UTF8(/path/to/gtmposixplugin)"

Attempting to configure an env descriptor without providing a suitable environment produces an IHBADENV error. Each EnvVarName is a legal POSIX environment variable name, consisting solely of ASCII letters, digits, and underscores ("_"), of which the first character must not be a digit; if configuration processing encounters a failure to meet this criterion, it also produces the IHBADENV error. To allow for permissible, non-graphic values^[1] of environment variables, and to allow environment variables to reference environment variables of the InfoHub itself (using the $ZTRNLNM() function), each Value is treated as a GT.M expr that the InfoHub evaluates before storing the result in its database.

	InfoHub Internals
Configuration processing stores Env descriptor information in the following nodes: ^InfoHubConf(InfoHubID,"EnvSetUp",1,BeginningSequenceNumber)=a??[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that an InfoHub process uses to manage its environment. ^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??"EnvSetUp")a??=[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that a Publisher process uses to adjust the environment provided to it by its InfoHub to be appropriate for a PipeLine process. Expression evaluation (implemented with indirection or XECUTE) also has the potential for side effects that can affect the InfoHub itself. To protect the InfoHub itself from side effects of evaluated expressions, the InfoHub processes Env descriptors in a routine which protects itself by: setting $ZROUTINES to the null string to prevent any new routines from being linked; creating a temporary global directory and database with $ZGBLDIR pointing there; executing an exclusive NEW; and receiving results in $ZTWORMHOLE, it being impossible to modify $ZTWORMHOLE as a side-effect of an expression. ($ZTWORMHOLE can itself be safely saved and restored in the calling routine to retain its originally intended use for triggers.)

InfoHub Internals

Configuration processing stores Env descriptor information in the following nodes:

^InfoHubConf(InfoHubID,"EnvSetUp",1,BeginningSequenceNumber)=a??[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that an InfoHub process uses to manage its environment.

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??"EnvSetUp")a??=[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that a Publisher process uses to adjust the environment provided to it by its InfoHub to be appropriate for a PipeLine process.

Expression evaluation (implemented with indirection or XECUTE) also has the potential for side effects that can affect the InfoHub itself. To protect the InfoHub itself from side effects of evaluated expressions, the InfoHub processes Env descriptors in a routine which protects itself by:

setting $ZROUTINES to the null string to prevent any new routines from being linked;
creating a temporary global directory and database with $ZGBLDIR pointing there;
executing an exclusive NEW; and
receiving results in $ZTWORMHOLE, it being impossible to modify $ZTWORMHOLE as a side-effect of an expression. ($ZTWORMHOLE can itself be safely saved and restored in the calling routine to retain its originally intended use for triggers.)

Example:

Env:LC_TIME='fr_FR.UTF-8'
Env:LANG='en_US.utf-8'

^[1]Quoting from IEEE Std 1003.1-2008: The values that the environment variables may be assigned are not restricted except that they are considered to end with a null byte and the total space used to store the environment and the arguments to the process is limited to {ARG_MAX} bytes.

PrevA	Up	A Next
A	Home	A

Defining an Env DescriptorChapterA 4.A Configuring an InfoHub

Defining an Env Descriptor

Defining an Env Descriptor
ChapterA 4.A Configuring an InfoHub