The d3tcl command allows execution of the D3 TCL commands directly from a UNIX shell.
d3tcl
d3tcl {d3tcl.command}
d3tcl -boot
| {d3tcl.command} | Executes a single D3 TCL command and returns to UNIX. Note: The d3tcl command logs on and off of D3 on every
execution. Remember that the UNIX shell must parse the d3tcl command before sending it to D3, and therefore, all special characters,
including the parenthesis, must be escaped to avoid errors.
|
| -boot | Boots the D3 machine. When the boot is completed, D3 returns control to UNIX rather than going to a D3 log on. This can be useful for shell scripts that are automatically run when the UNIX machine is booted. |
The d3tcl command is installed as a UNIX shell script during D3 installation. To function properly, the d3tcl command requires that the user set several shell environment variables appropriately:
| PICKVM | D3 virtual machine name. If this is not set, then the default of pick0 is assumed. |
| PICKUSER | D3 user name. If not set, the D3 user is assumed to be the
same as the UNIX user. Note: The user name is obtained from either
the %username variable or the user name is supplied
with the -u option, therefore the user name cannot contain spaces.
|
| PICKUPASS | D3 user password. This should only be set if a user password is present. |
| PICKMD | D3 master dictionary. This must be set unless the user macro automatically logs into a dictionary. |
| PICKMDPASS | D3 master dictionary password. This should only be set if a master dictionary password is present. |
Several variants of the d3tcl command are available. The d3tcl command by itself pushes a D3 TCL shell above the current UNIX one. This is equivalent to the UNIX sh command. Logging off of D3 automatically returns to UNIX.
The sequence of commands below set up the necessary environment variables, push a D3 TCL shell, execute a few d3tcl commands, and exit back to the UNIX shell.
$ PICKUSER="dm"; export PICKUSER $ PICKMD="dm"; export PICKMD $ d3tcl :who 6 dm dm :time 08:14:12 25 Feb 2003 Tuesday :off $
Displays the input and output (bsh or ksh is assumed to be the active UNIX shell).
The d3tcl command can be easily incorporated into UNIX shell scripts. The example below is a shell script called up, which invokes the D3 Update processor from a UNIX shell:
#shell script to run update processor exec d3tcl u $*
This shell script should be typed into an editor, such as vi, and saved into the UNIX file system. Then, it must have its permissions changed so that it is executable with a chmod a+x up command. Finally, it must be placed in a directory that is contained in all users’ $PATH variables. The users may have to log off and log on again in order to recognize the new command.
To run the shell script, type:
up bp date
Invokes the Update processor on the date program in the bp file. It can be filed, or even run by pressing CTRL+XR. When finished, the Update processor returns back the UNIX shell.
The d3tcl command also has the capability of transferring data from D3 to UNIX via the pipe. The example below places a partial listing of the D3 bp file, into the UNIX file bp.list.
d3tcl list bp sampling 5 \(hcnb | tr -d "\015" > bp.list
Notice that the ( command must be preceded by a \ character, because the UNIX shell would otherwise interpret the ( as a special character. Also, notice that the output must first be piped into the tr command, which strips off carriage returns. This is necessary because D3 outputs in raw mode.
In the next example, various UNIX shell capabilities are demonstrated. The first line puts the name of the first program in the bp file into the UNIX shell variable PROGRAM. Next, the variable is then executed using export so that the subshells can access it. Finally, the first program in the bp file is copied into an item called backup and the results of the operation are stored in the UNIX log file.
PROGRAM=‘d3tcl list bp sampling 1 \(hcnb | tr -d "\015"‘ export PROGRAM echo "backup\r" | d3tcl copy bp $PROGRAM \(o | tr -d "\015" > log
If the \r is left off of the input pipe, the command terminates and returns to UNIX without doing anything.
A different mode is used if the actual commands are piped into the d3tcl program as displayed below.
$ echo "select bp with a0 \"date]\"\rcompile bp\r" | d3tcl :select bp with a0 "date]" [404] 2 items selected out of 279 items. :compile bp date ***************... [241] successful compile! 3 frames used. date.iconv ****** [241] Successful compile! 1 frame(s) used. :
Displays the input and output (bsh or ksh is assumed to be the active UNIX shell).
When commands are piped in as the only input to the d3tcl statement, D3 behaves exactly as if those commands were typed directly at the keyboard. All simulated input and all output, including prompts, are sent to standard-out. Also note that multiple commands can be passed to the d3tcl program using this mode and that select lists are preserved between each of those commands, provided they are executed within a single execution of the d3tcl program.