tcl.@ Definition/TCL

tcl.@

Command tcl.@ Definition/TCL
Applicable release versions: AP 6.2
Category TCL (746)
Description indicates a Pick shell variable.

A Pick shell variable.name may contain any combination of alphabetic and numeric characters. The period and underscore characters are also valid.

Shell variables are pushed up and down all execute levels and persist until logoff. They are essentially the TCL analog of BASIC named common variables.

A Pick 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" verb. The following user variables are examined by the system. Note that variables begining with the word "sys" are reserved for future system usage. The "$" character is optional, but is recommended for usage on all modifiable variables.

@$MESSAGES The contents of this variable are used to locate the system error messages. The format 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 will use this alternate file until the user logs off the file.

@$PATH The contents of this variable are used to direct the system to default accounts for verbs, 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 following format: "account.name1,account.name2,account.name3...". Up to 8 account names may be listed. Note that there must NOT be a comma at the end of the list. When doing a "set" of this variable, the system pre-checks each of the account names. If an error is found, then the text of the list will be terminated with the "(ERR!)" string.

@$PROMPT The contents of this variable dictate the appearance of the TCL prompt. The system expects this variable to have the following format: "prefix,prompt1,prompt2". The "prefix" parameter is a textual indicator which is displayed before the prompt. The "prompt1" parameter is the prompt character to be used normally at TCL. The "prompt2" parameter is the prompt character to be used when a select list is active.

@$SYS.COMPILER The contents of this variable dictate the compatibility setting of the BASIC compiler. See the "$options" token for the BASIC compiler for more information about this.

Several variables have values which are dynamically computed at run-time. The currently supported list includes the following:

@AM Attribute Mark
@FM Attribute Mark (for licensee compatibility)
@VM Value Mark
@SVM SubValue Mark
@SM SubValue Mark (for licensee compatibility)
@USER User name
@WHO User name (for licensee compatibility)
@ACCOUNT Account
@LOGNAME Account (for licensee compatibility)
@PIB User Pib
@USERNO 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
@ID Same as "*A0" (for licencee compatibility)
@SYSTEM.RETURN.CODE Returns number of items processed by the most recent access statement.

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

The second version of the @ syntax executes the specified TCL command and replaces the @`...` 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 expansions (those expansions 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 "@" character appears within single quotes, then the corresponding variable is NOT expanded. Also, the sequence "@@" is expanded into "@". Finally, any shell variable identifiers which are not found in the current list are NOT expanded at TCL.

TCL shell variables are passed up and down between levels so they may be used freely across BASIC execute boundaries.

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

The conversion processor expands conversion values beginning with the "@" character to their respective values. Note that transitive expansions are not allowed in this case for performance reasons.

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

Shell variables may be referenced and assigned within a BASIC program. Note that the TCL shell capability is not available from BASIC. Also, shell variables cannot be assigned directly by a complex BASIC statement (like "locate" for instance). They must be assigned with simple assignement statement.
Syntax @{$}variable.name}
@`TCL.Command`
Options
Example
The following sequence of commands shows some typical interraction 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|@{time}xxx|@date
john|15:27:12xxx|17 May 1994
PROD>unset prompt
:env
myfile=dm,bp,

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 "itm1" which contains 
the text "abc123". Notice how the conversion can be modified without 
changing the attribute definition:
set mycv=mcu
list junk xx
Page   1    junk

junk...... xx.........

1          ABC123

[405] 1 items listed out of 1 items.
set mycv=mca
list junk xx
Page   1    junk

junk...... xx.........

1          abc

[405] 1 items listed out of 1 items.

Multi-lingual 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" (which is the default), and that the French ones are in 
"dm,msg.French,". By default, all users get their messages from 
"dm,messages,". To cause French speaking users to use French error 
messages, it is a simple matter of inserting the following line as the first 
thing in each French users' user macro:

set messages="dm,messages,"
Purpose
Related tcl.penv
tcl.set
tcl.unset
ue.91
tcl.tcl-prompt
tcl.field
tcl.background
basic.$options