d3 command

The d3 command starts the D3 virtual machine or a D3 user process.


 d3 {{[-0|-a boot.arg|-port.number|-f|-q|-k|-qf|-ql|-qn] } {-n config.file} 
 {-t tty} {-y stty.arg} {-d data.arg} {-b} {-l} {-i nice} {-icrlf} {-key n}
 {[-printer|-pprinter]}} {-D} {-s} {-step} {-w} {-u /ttelnet.port,
 server.hostname} {-L lang.file}{-r} {haforcecheck}


-0 Starts the virtual machine.

This process initializes the virtual machine. All other processes wait for the coldstart to complete its initialization before actually starting. Once the virtual machine starts, line 0 can be disconnected by typing exit or disc on any other line. Issuing a d3 -0 again reconnects to port 0 of the virtual machine if it is booted.

-a boot.arg Starts a virtual machine automatically.

This process initializes the virtual machine. All other processes wait for the coldstart to complete its initialization before actually starting.

This option is similar to the 0 option, with the difference that the system does not prompt for a boot option. Instead, it takes one-character commands from the boot argument among the boot options: x, f, or a.

When encountering the x command, the system polls the keyboard for a period of bootsleep seconds (the default is 3 seconds) for a user intervention. If any key is pressed during this short period, the system defaults to a manual boot. Bootsleep can be redefined in the D3 configuration file by adding the statement bootsleep n.

The boot argument specified is a string of commands if typed by the operator for a manual boot. When the command involves a tape, the tape is assumed to be ready. Therefore, the c (for continue) should not be included in the string.

-b Disables the ABS protection mechanism for a particular process.

This option is required when loading third party applications into boot ABS, or loading patches.

-D Enables the monitor debugger.

On entry, the process enters the monitor debugger. This option is ignored if the process started is a phantom or a printer. Type g, and then press Enter to start the process.

-dcdon Enables DCD protocol handling.

This is similar to the dcd on command at TCL, with the exception that this option does not change any terminal characteristics. This option, along with the y option, allows lines at the logon prompts to log off and/or restart after an interruption, such as a power failure.

-d data.arg Stacks data for the process once it is activated. The data argument specified is any string that contains displayable characters and commands prefixed by a backslash.
Note: The string is subjected to the normal shell parsing. Thus, the backslash must be escaped, or the entire string must be enclosed in single quotation marks. The data argument specified can be contained in a UNIX file by using the shell command substitution mechanism. For example, using back quotation marks:
 -d ~‘ cat /usr/lib/pick/logon~‘

All line feeds in the input string are converted to carriage returns. These commands include:

\f Turns echo off. The stacked data is not displayed.
\m Waits until the D3 virtual machine enters the multi-user mode.

The maxusers TCL command should be included in the user-coldstart macro after all system and application initializations are completed.

\n Turns echo on. The stacked data is displayed.
\r Inserts a carriage return.

When activating a process for the first time, the system reads one character, then empties the type ahead buffer. Therefore, stacked data should always start by the sequence \r, followed by the real log on sequence.

\\ Inserts a backslash.
-f Restarts the flusher process. If the flusher process is incorrectly killed, this option can be used to restart the flusher.

This option should never be used if the flusher is already running.

-icrlf Ignores the linefeed character when sent after a carriage return.
-i nice Sets the relative priority of the D3 process, compared to other processes (D3 or not) running on the system.

The legal nice values range from -20 to +19. The value -20 returns the highest priority and +19, the lowest.

-k Kills all processes attached to the specified virtual machine.

The user is prompted with Are you sure you want to kill d3? (y/n=cr).

If a y is not entered, then the kill attempt is aborted. Otherwise the kill proceeds. A logoff should be attempted first, followed by a terminate signal, which should send the process back to UNIX. If the terminate signal has no effect, a kill is attempted, which removes the process.

Warning: The -k command should be used only in extreme situations. This is not the normal process to stop a virtual machine.
-key n Specifies the key value for the virtual machine you are attempting to connect to. Use this form instead of specifying the configuration file.
-l Retains the log on UNIX user-ID.

This option logs the process as the same UNIX user as the one used to log on to UNIX. This option overrides the user definition contained in the configuration file. The user is isolated from the other D3 users. This option should be used only for users who want their own UNIX environment underneath the D3 process or to perform a system configuration, which requires root access.

-L lang.file Specifies an alternate language file for boot-time messages and errors to be displayed in a different language.
-m Restarts the signal handler process. If the signal handler process is incorrectly killed, this option can be used to restart it.
This option should never be used if the signal handler is already running.
-n config.file Specifies the name of the configuration file. If not specified, the default file name is pick0 in the current directory or alternately in the /usr/lib/pick directory.


Specifies that the port is to be used as a phantom, or as a process not attached to a physical port.
Note: These three options are reserved for use by D3 utilities.
-port.number Starts a user process.

Expressed in decimal from 1 to the maximum allowed number of users, this starts a D3 process on a specified port, when necessary, to control the port on which process it is running. If the port is not specified, the system allocates the first available port.

-printer Specifies that the port is to be used as a printer.

This option suppresses the messages Connected to virtual machine and Disconnected from virtual machine, but does not suppress the normal D3 message processes, such as the D3 logon message.

-q Query command. Queries information about the specified virtual machine, which can be executed by any process.

If the virtual machine is started, then the command returns exit code 0 to the shell. Otherwise a value of 1 is returned. This tests the existence of the virtual machine from the shell.

-qf Displays information about the flushers.
-ql Query license command. Queries information about the licenses for the specified virtual machine, which can be executed by any process.
-qn Lists all active nailed telnet and ODBC connections to D3. Results include the PIB, type, UNIX Process ID and IP Address.
-r Resets the PIB.
-s Enables silent mode.

If used with the -0 command, the D3 machine boots, and returns directly to UNIX.

If used on a normal line, output of log on and log off messages and user macros are suppressed, and any attempt to log off returns directly to UNIX.

Because output is suppressed, the -s flag must be used with the -d flag, followed by a string containing:
  • User name
  • User password
  • Master dictionary
  • Master dictionary password (when applicable)
This is so that the user is logged on to D3 automatically. The -s flag is used by the d3tcl UNIX shell script.
-step Changes the system-coldstart macro from an n-type to an m-type so you can single-step the coldstart process.
-t tty Specifies which port is to become the terminal for the process. The device is assumed to be on the /dev special files directory.

For AIX: If the port is not specified, the terminal is stdout or stdin, unless it has been redirected.

For Linux: Option is normally intended to be used only in the /etc/inittab file. When this field is present, the system assumes the user process is started automatically, and, behaves a bit differently when starting. It waits for line 0 to start if it is not already started.
-u /ttelnet.port ,   server.host.name Starts D3telnet on the specified telnet port, where the server host name is specified.

This option starts the D3 Telnet Server on the Telnet port number specified and waits for the connection from a Client. The Client makes the connection by using Telnet on the Server host and the same Telnet port.

-w Waits for the device specified by the -t option to be created.

This option instructs the D3 monitor that the device does not exist yet, thus avoiding the "no such file" error. This is used in configurations where the /dev/ entry is created dynamically by a UNIX daemon. The process polls the specified device and waits until it is created as a pipe, block, or character device. This option is ignored if the -t option is not specified as well.

-y stty.arg Changes the default port setting for the process.

The stty argument specified is any stty command. If more than one element is changed, they must be separated by spaces and the whole argument is enclosed in quotation marks. (Refer to the examples.) When the process terminates, the port characteristics are not reset to their original values.

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.


Example 1

This code starts the virtual machine pick0 (default).
 d3 -0

Example 2

This code starts the virtual machine mymachine.
 d3 -n mymachine -0

Example 3

This code starts a user process on the virtual machine pick0 (default), on the first available port (default PIB ' ').

Example 4

This code starts a user process on the virtual machine pick0 (default), on port 5.
 d3 -5

Example 5

This code starts a user process on the virtual machine mymachine, on port 7.
 d3 -n mymachine -7

Example 6

This code displays information about the virtual machine pick0 (default name).
 d3 -q

Example 7

This code starts the virtual machine 0 on /dev/tty2. This statement is typically included in the /etc/inittab file.
 d3 -0 -t tty2

Example 8

This code starts a user process on /dev/tty6 as a printer. It changes the baud rate to 9600 and sets the parity to odd. This statement is normally included in the /etc/inittab file.
 d3 -3 -t tty6 -y "9600 parenb -parodd" -printer

Example 9

This code automatically boots the virtual machine, performs an ABS restore from device 3, and then issues an x option.
 d3 -a a3x

Example 10

This code starts a user process on the first available port, and then logs on as dm on the account acct. The commands term ibm3151 and menu are then executed.
Note: The \r ensures the process logged on properly the first time after a boot.
 d3 -d ’\r\mdm\racct\rterm ibm3151\rmenu\r’

Example 11

The shell script boot.ap uses the -q option to test whether the virtual machine is booted or not.
  • If the d3 -q command returns a null exit code (ok), then the virtual machine is already booted so that D3 TCL returns immediately.
  • If ok is not returned, the virtual machine is booted automatically.
 001 # Test if VM is active. else boot it
 002 d3 -q > /dev/null
 003 if [ $? ! -eq 0 ]
 004 then
 005 -a x
 006 fi

Example 12

This code enters the D3 virtual machine, retaining the current UNIX user-ID (root, because of su).
 password:(enter ’root’ password)
 $d3 -l

Example 13

This code starts a background D3 Telnet Server process, which connects to the default D3 virtual machine pick0 on PIB 7 and waits for connection from the Client. If the Server host name is serverhost, a UNIX Client makes the connection by using the Telnet serverhost 2007 command in a UNIX shell.
 $d3 -7 -u /t2007,serverhost &

Example 14

This code returns the PIB, type, UNIX Process ID, and IP Address for all current nailed Telnet and ODBC connections to D3.
 d3 -qn
 /dev/pts/1: Connected to Virtual Machine 'pick0:AIX'.
 PIB       Type       On PID        IP_Address
 16        1 1        3874852