# @ shell variable

The `@` character indicates a D3 shell variable.

## Syntax

```
@[{]}variable.name[}]|@[{]$variable.name[}]
@‘tcl.command‘
```
Note: For this command only, the braces are part of the
command and must appear as a pair. The single quotation marks must
be backward quotation marks.

A D3 shell variable name can
contain any combination of alphanumeric characters. The period and
underscore are also valid.

A D3 shell variable can be modified
with the TCL command `set *variable.name*{=*value*}`, and cleared with the command `unset *variable.name*`. The current list of user variables
can be displayed with the penv command. The
following list of user definable variables have special meaning to
the system as described below.

| @$messages | Contents of this variable are used to locate the system error messages. The form of this variable is the full path name of the desired alternate messages file. To allow the use of an alternate messages file, insert a line similar to the following, "set messages=dm,msg.file.name,", as the very first line of the user macro. All subsequent error messages uses this alternate file until the user issues a new set command or logs off the system. |
| --- | --- |
| @$path | Contents of this variable are used to direct the system to default accounts for commands, BASIC main programs, BASIC subroutines, and files. When the system fails to find one of these objects within the current master dictionary, it successively searches each of the account master dictionaries in this list. The list is of the form: ```
account.name1,account.name2,account.name3...
``` Up to eight account names can be listed. Note: There must not be a comma at the end of the list. When doing a set of this variable, the system prechecks each of the account names. If an error is found, the path is cleared and the message "[994] account not found" is displayed. Remote accounts are not supported in the path. Referencing a remote account will also clear the path and display the message "[504] That feature is not supported on a remote file". |
| @$prompt | Contents of this variable dictate the appearance of the TCL prompt. When defining this variable, the following syntax must be used: ```
prefix,prompt1,prompt2
``` Prefix is a textual indicator that displays before the prompt. Prompt 1 is the prompt character to be used at TCL. Prompt 2 is the prompt character to be used when a select list is active. |
| @$sys.compiler | Contents of this variable determines the compatibility setting of the BASIC compiler. |
The second version of the `@` syntax executes
the specified TCL command and replaces the `@`...`` (single backward quotation marks) sequence with the output of that
command.

Substitution of TCL shell variables is active for all
TCL commands including those issued from macros, paragraphs, interactive
commands, and BASIC executes. Transitive replacements (those replacements
whose values contain other variable definitions) are allowed except
where noted below.

At TCL, several rules are in effect to prevent
shell variables from interfering with previously existing code. If
the `@` displays within single quotation marks, then
the corresponding variable is not replaced. The sequence `@@` is replaced by @.

TCL shell variables are
passed up and down all execute levels so that they may be used freely
across BASIC execute boundaries. They are essentially the TCL analog
of BASIC named common variables.

All shell variables are released
and cleared when logging off of the system.

The conversion processor
replaces conversion values beginning with the `@`,
using their defined values. Transitive replacements are not allowed
in this case for performance reasons.

The menu processor replaces
all menu definitions based on the above mentioned rules for TCL.

Shell variables may be referenced and assigned within a BASIC
program. The TCL shell capability is not available from BASIC. Shell
variables cannot be assigned directly by a complex BASIC statement
(for example, locate). They must be assigned with
an assignment statement.

If a shell variable occurs directly
next to other text, the identifier (starting after the `@` , but before the $, if present) must be surrounded
by the `{` and `}` characters.

Note: Variables beginning with the word `sys` are reserved
for future system usage. The `$` character is optional,
but is recommended for usage on all user defined variables.

Several variables have values that are read only and are either
static or dynamically computed at run time. The supported static variables
include:

| @am | Attribute mark. |
| --- | --- |
| @im | Item mark (for licensee compatibility). |
| @fm | Field mark (for licensee compatibility). |
| @sm | Subvalue mark (for licensee compatibility). |
| @svm | Subvalue mark (for licensee compatibility) |
| @tm | Text mark (also known as start buffer; for licensee compatibility). |
| @vm | Value mark. |
The supported dynamically computed variables include:

| @user | User name. |
| --- | --- |
| @who | User name (for licensee compatibility). |
| @account | Account. |
| @logname | Account (for licensee compatibility). |
| @pib | User PIB. |
| @usern | User PIB (for licensee compatibility). |
| @time | Current system time. |
| @date | Current system date. |
| @day | Current system day of month. |
| @month | Current system month of year. |
| @year | Current system 2-digit year. |
| @level | Current execution level (for licensee compatibility). |
| @system.return.code | Returns the number of the items processed by the most recent AQL statement. Returns a -1 if the previous command failed. |

## Example(s)

The sequence of commands below
show the typical interaction from TCL:

```
set prompt=prod,>,?
prod>set myfile="dm,bp,"
prod>who
70 john ba
prod>penv
prompt=prod,>,?
myfile=dm,bp,
prod>select @$myfile sampling 5
[4042] 5 items selected out of 5 sampling items
prod?list @$myfile heading "report from @logname"
report from ba
dm,bp,........
color
pick
set-imap
shp-kill
restore-accounts
[405] 5 items listed out of 5 items
prod>display @system.return.code
5
prod>display @who|’@who’|@{time}xxx|@date|@dateabc
john|’@who’|15:27:12xxx|17 Feb 2003|@dateabc
prod>display @‘time‘
15:27:14 17 Feb 2003 Monday
prod>unset prompt
penv
myfile=dm,bp,
```
Note: This feature requires the use of single backward quotation
marks.

Shell variables can also be accessed from conversions.
Assume that a file called junk has the following attribute-defining
item:

```
dict junk 'myattr' size = 45
dictionary-code a
attribute-count 1
substitute-header
structure
output-conversion @$mycv
correlative
attribute-type L
column-width 10
...
```
Assume that the file contains one item called 1 that contains
the text abc123. Notice how the conversion can be modified without
changing the attribute definition:

```
set mycv=mcu
list junk myattr

page 1 junk
junk...... myattr.......
1 ABC123
[405] 1 items listed out of 1 items.

set mycv=mca
list junk myattr

page 1 junk
junk...... myattr.......
1 abc
[405] 1 items listed out of 1 items.
```
Multilingual systems are facilitated by use of the `@$messages` variable. Assume that a system exists with 30
English speaking users, and 20 French speaking users. Assume that
the standard English messages are stored in dm,messages (the default), and that the French are in dm,messages,french. By default, all users get their messages from the dm,messages, file. To cause French speaking users to use French error messages,
it is a matter of inserting the following line as the first thing
in each French users' user macro:

```
set messages=dm,messages,French,
```

## See also

- [set command](https://d3codex.com/tcl/set-command/)

---
Source: https://d3codex.com/tcl/shell-variable/ - part of the D3Codex reference.