tcl.environ Verb: Access/Unix

tcl.environ

Command tcl.environ Verb: Access/Unix
Applicable release versions: AP/Unix
Category Unix (24)
Description manipulates Unix shell environment variables from TCL.
Commands may be passed from the TCL command line or from an item.

It is possible to set and test shell variables, as well as execute TCL commands (including Unix commands prefixed by "!") under control of the shell variables.

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

A "command" is a sequence of non-blank 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 may be issued on the same line by separating each command with a ";" (semi-colon).

Command Substitution:

Text enclosed in "back quotes" (`text`) is considered a TCL command, which is executed, its output captured and the result inserted in the command in place of the "back quoted" command. 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 "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 one-digit number, it is a positional parameter in the range 0 to 9.

"$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 "environ" or a Shell parameter.

Parameter substitution is performed before the command is parsed and before command substitution.

Shell parameter (or environment variables) may 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 following Shell variables are available:

$? This 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.

$$ This returns the Unix ID (PID) of the current Pick process.

$! This returns the current Pick port.number.

$n This indicates the positional parameter "n" to substitute. Must be in the range 0 through 9

$USER This returns the current Pick user-id.

$ACCT This returns the current Pick account name.

$TIME This returns the current Pick internal time.

$DATE This returns the current Pick internal date.

${parameter}
The value of the Shell environment variable "parameter" is substituted. The "braces" 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 may be expressed in either of two ways:

argument1 {!}operator argument2

Where "argument" is either a string, a number, or a parameter, and "operator" is either "=", "<", ">", "<=" or ">=".

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

Where "argument" is either a string, a number, or a parameter and "op" is either:

-f file

The condition is true if the specified file exists and can be opened.

-r file item-id

The condition is true if the specified item-id exists and can be read.

-v file item-id value

The condition is true if the specified value exists and is not empty.

-n string

The condition is true if "string" has a non-zero length.

The "!" before the operator negates the condition.


Environ Commands:

chain {file.reference} item-id

This causes "environ" to begin executing the commands in the given item-id. If "file.reference" is omitted, md is assumed. Control does not return to the calling "environ" program.

exit

This causes "environ" to terminate.

read

This reads one line from the terminal and assigns each word to the positional parameters "$1", "$2", etc. Up to 32 words are moved into the positional parameters.

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

This sets (-) or resets (+) the given "environ" flags. This setting overrides the flags set on the command line.

shift {n}

The positional parameters "$n+1" "$n+2" etc, are renamed "$1" "$2" etc. If "n" is omitted, "1" is assumed.

Invocation flags:

-c string

Reads commands from "string". If "string" contains more than one word, it must be enclosed in single quotes.

-f {file.reference} item-id

Reads commands from "item-id" in "file.reference". If "file.reference" is omitted, md 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. Display is prefixed by a "+".
Syntax environ {-x} {-n} {-c string|-f {file.reference} item-id}
Options
Example
1) :environ -c 'term $TERM'

This sets the Pick terminal type definition to the same value as defined in 
Unix.

2) :environ -f ${USER}.env

Evaluates the value of the variable $USER and executes the specified environ 
script in the current dictionary. Note the usage of the braces around the 
variable name, since it is not followed by a space. 

3) :environ -c 'TERM=wyse50'

This sets the Unix terminal driver to a Wyse 50.  The verb "env" 
verifies the new environmantal parameter.

4) :environ -f myprofile

Executes the commands contained in the (md) item "myprofile", as 
defined below, which tests for the existence of the Unix "TERM" 
variable, uses it as an argument to the TCL "term" command if the 
corresponding item exists in the "dm,devices," file. It also sets a 
Shell variable "PICKLOGON" equal to the Pick date and time, and a 
Shell variable "PICKWHO" equal to the usual TCL "who" 
command. Finally, it tests for the existence of an item 
".profile.username" and executes it if it exists. 

md myprofile
001 *
002 * Set Pick 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 Pick logon time, using
011 * command substitution (back quotes around time).
012 PICKLOGON=`time`
013 *
014 * Set a shell variable equal to port number,user id and MD
015 PICKWHO=$! $USER $ACCT
016 *
017 * And go execute any private environment, if item exists
018 if -r md .profile.$USER; then chain .profile.$USER; end
Purpose
Related basic.%putenv
basic.%getenv
tcl.env
tcl.!.unix
basic.%malloc
tcl.disc
tcl.environ.link