# 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 =, , =. |
| argument1 | Specifies first string, number, or parameter. |
| argument2 | Specifies second string, number, or parameter. |
or

```
{!} 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.

## See also

- [! command](https://d3codex.com/tcl/exclamation-command/)
- [%getenv() function](https://d3codex.com/pickbasic-flashbasic/percent-getenv-function/)
- [%malloc() function](https://d3codex.com/pickbasic-flashbasic/percent-malloc-function/)
- [%putenv() function](https://d3codex.com/pickbasic-flashbasic/percent-putenv-function/)
- [disc command](https://d3codex.com/tcl/disc-command/)
- [env command](https://d3codex.com/unix/env-command/)

---
Source: https://d3codex.com/tcl/environ-command/ - part of the D3Codex reference.