@ shell variable

The @ character indicates a D3 shell variable.


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:
Up to eight account names can be listed.
  • 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 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.


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

set prompt=prod,>,?
prod>set myfile="dm,bp,"
70 john ba
prod>select @$myfile sampling 5
[4042] 5 items selected out of 5 sampling items
prod?list @$myfile heading "report from @logname"
report from ba
[405] 5 items listed out of 5 items
prod>display @system.return.code
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
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
output-conversion @$mycv
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