environ Command

The environ command manipulates the UNIX shell environment variables from TCL.

Syntax

environ {-x} {-n} {-c string|-f {file.reference} item-ID}

Parameter(s)

-c string	Reads commands from the specified string. If the string contains more than one word, it must be enclosed in single quotation marks.
-f {file.reference} item-ID	Reads commands from the item-ID in the file reference. If the file reference is omitted, then the master dictionary is assumed.
-n	Reads commands, but does not execute them. This should be used with the -x flag to investigate the effect of an environ program for debugging purposes.
-v	Prints commands and their arguments as they are read, whether they are executed or not.
-x	Prints commands and their arguments as they are executed. The display is prefixed by a plus sign.

Description

Commands can be passed from the TCL command line or from an item. It is possible to set and test shell variables, and execute TCL commands (including UNIX commands, prefixed by an exclamation point) under control of the shell variables.

If no arguments are provided, the commands are read from the item .profile in the master dictionary of the current account.

A command is a sequence of words separated by spaces. If the command starts with an asterisk, it is treated as a comment and ignored. If the first word is not one of the key words recognized by environ, the command is treated as a TCL command, which is then executed. Commands are read from either the TCL sentence or from an item. Multiple commands can be issued on the same line by separating each command with a semicolon.

Example(s)

Causes environ to begin executing the commands in the specified item-ID. If the file reference is omitted, the master dictionary is assumed. Control does not return to the calling environ program.

chain {file.reference} item-ID

Causes environ to terminate.

exit

Reads one line from the terminal and assigns each word to the positional parameters $1, $2, and so on. Up to 32 words are moved into the positional parameters.

read

Sets (-) or resets (+) the specified environ flags. This setting overrides the flags set on the command line.

set {[+|-] flags}{arguments...}

These positional parameters $n+1, $n+2, and so on are renamed $1, $2, and so on. If n is omitted, 1 is assumed.

shift {n}

Command Substitution

Text enclosed in backward quotation marks is considered a TCL command. When executed, the results of the output are captured and inserted into the command replacing the command enclosed in single quotation marks. Attribute marks in the output are converted to a space. Command substitution occurs before the command is parsed.

If the command is a UNIX command, only the results of the stdout is captured. Use the UNIX redirection to send stderr to stdout, if necessary.

Parameter Substitution

The $ character is used to introduce parameters for substitution. If the parameter is a 1-digit number, it is a positional parameter in the range of 0 through 9. The shell parameter $0 is the concatenation of all positional parameters from $1 through $9, with one space inserted between each value.

Positional parameters are set by the set environ statement. The parameter name can be one reserved keyword interpreted locally by the environ command or a shell parameter.

Parameter substitution is performed before the command is parsed and before command substitution. Shell parameters (or environment variables) can be assigned values by the command:

name=value

Variables set in this manner are automatically marked for export to the environment of any subsequently executed UNIX commands.

The shell variables include:

$?	Contains the value of the return code of the last executed command. If the last command was a UNIX command, this value is the exit code. If it was a TCL command, this value is the error message number returned.
$$	Returns the UNIX ID (PID) of the current D3 process.
$!	Returns the current D3 port number.
$n	Indicates the positional parameter n to substitute (must be in the range 0 through 9).
$USER	Returns the current D3 user-ID.
$ACCT	Returns the current D3 account name.
$TIME	Returns the current D3 internal time.
$DATE	Returns the current D3 internal date.
${parameter}	Value of the shell environment variable parameter is substituted. The { } are required only if the parameter is not followed by a space.

Control Structures

if condition

then

{elif condition}

{then}

else

end

where condition is evaluated and the commands are executed according to the result.

Conditions can be expressed in one of two ways:

argument {!}operator argument2

!	Displays before the operator negates the condition.
operator	Either =, <, >, <= or >=.
argument1	Specifies first string, number, or parameter.
argument2	Specifies second string, number, or parameter.

{!}op argument1 {argument2{...}}

!	Displays before the operator negates the condition.
op	-f	A file—The condition is true if the specified file exists and can be opened.
	-r	A file item-ID—The condition is true if the specified item-ID exists and can be read.
	-v	A file item-ID value—The condition is true if the specified value exists and is not empty.
	-n	A string—The condition is true if the string has a nonzero length.
argument1	Specifies the first string, number, or parameter.
argument2	Specifies the optional second string, number, or parameter.

Example(s)

Sets the D3 terminal type definition to the same value as defined in UNIX.

environ -c ’term $TERM’

Evaluates the value of the variable $USER and executes the specified environ script in the current dictionary.

environ -f ${USER}.env

NOTE	The braces around the variable name are used since it is not followed by a space.

Sets the UNIX terminal driver to a Wyse 50. The command env verifies the new environmental parameter.

environ -c ’TERM=wyse50’

Executes the commands contained in the master dictionary item myprofile and tests for the existence of the UNIX TERM variable. if the corresponding item exists in the dm,devices, file, it uses the TERM variable as an argument to the TCL term command. It also sets a shell variable, D3LOGON, equal to the D3 date and time, and a shell variable, D3WHO, equal to the usual TCL who command. Finally, it tests for the existence of an item .profile.username. If it exists, the item is then executed.

environ -f myprofile

md myprofile

001 *

002 * Set D3 Term if the shell term variable is defined.

003 if $TERM != ""

004 then

005 if -r dm,devices, $TERM; then term $TERM; end

006 else

007 display term is not defined.

008 end

009 *

010 * Set a Shell variable equal to D3 logon time, using

011 * command substitution.

012 D3LOGON=‘time‘

013 *

014 * Set a shell variable equal to port number,user-ID and MD

015 D3WHO=$! $USER $ACCT

016 *

017 * And go execute any private environment, if item exists

018 if -r md .profile.$USER; then chain .profile.$USER; end

NOTE	Backward quotation marks are required around time.