d3tcl command (UNIX)
.mdThe d3tcl command allows execution of the D3 TCL commands directly from a UNIX shell.
Syntax
d3tcl
d3tcl {d3tcl.command}
d3tcl -boot {haforcecheck}
Parameter(s)
| {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. |
| haforcecheck | Host Authentication, Force Authentication Check option. Allows controlling whether D3 prompts for logon credentials or whether D3 uses the client's Operating System credentials for logging on. If this option is used, clients will be prompted for their user-id and password when attempting to log on to D3. These credentials are then passed down to the operating system for authentication. Any users item passwords will now be ignored. Note that UNIX user-ids are case-sensitive. If this option is not used, clients will not be prompted for such credentials and will be taken directly to the md prompt. Note that doing an off behaves the same as an exit since the logon prompt was bypassed during the initial log on. See the Host Authentication topic in the System Administration Guide for more information. |
Description
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.
login prompt and user macro are executed without output.
The master dictionary macro is executed normally. Example(s)
The sequence of the following commands set up the necessary environment variables, push a D3 TCL shell, execute a few d3tcl commands, and exit back to the UNIX shell.
Example 1
This example shows the input and output (bsh or ksh is assumed to be the active UNIX shell).
$ PICKUSER="dm"; export PICKUSER $ PICKMD="dm"; export PICKMD $ d3tcl :who 6 dm dm :time 08:14:12 25 Feb 2003 Tuesday :off $
Example 2
The d3tcl command can be easily incorporated into UNIX shell scripts. The following example 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 might have to log off and log on again to recognize the new command.
To run the shell script, type:
up bp date
This invokes the Update processor on the date program in the bp file. It can be filed or run by pressing CTRL+XR. When finished, the Update processor returns back to the UNIX shell.
Example 3
The d3tcl command also has the capability of transferring data from D3 to UNIX via the pipe. This example 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.
Example 4
In this 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 sub-shells 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, shown as follows:
$ 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. :
This shows 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.