tcl.ap.unix Verb: TCL2/Unix

tcl.ap.unix

Command tcl.ap.unix Verb: TCL2/Unix
Applicable release versions: AP/Unix, AP 6.0
Category Unix (24)
Description starts the Pick virtual machine or a Pick user process.

-0
Starts the virtual machine. This process has the responsibility to initialize the virtual machine. All other processes will wait for the coldstart to complete its initialization before actually starting. Once the virtual machine is started, the line 0 can be disconnected, by typing 'exit' or 'disc', on any other line. Issuing 'ap -0' again will simply reconnect to the virtual machine if is is booted.

-a bootarg
Starts a virtual machine automatically. This process has the responsibility to initialize the virtual machine. All other processes will 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 "bootarg" 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 Pick configuration file, by adding the statement 'bootsleep n' or by using the TCL command "config options". "bootarg" is a string of commands as 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.

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

-q
Query. This command can be executed by any process to get information about the specified virtual machine. If the virtual machine is started, then the command returns exit code "0" to the shell, otherwise a value of "1" is returned. This allows testing the existence of the virtual machine from the shell.

-k
This command kills all processes attached to the specified virtual machine. First, a Pick logoff is attempted, 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. This command should be used only in extreme situations. This is not a normal way to stop a virtual machine.

-n configfile
This specifies the name of the configuration file. If not given, the default file name is "pick0" in the current directory or alternately in the "/usr/lib/pick" directory.

-t tty
This option specifies which port is to become the terminal for the process. The device is assumed to be on the "/dev" special files directory. If not specified, the terminal is "stdout/stdin", unless it has been redirected, (the usual case on AIX systems). This 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 started already.

-y sttyarg
This option allows changing the default port setting for the process. "sttyarg" is any "stty" argument. If more than one element is changed, they must be separated by spaces and the whole argument enclosed between double quotes (see examples below). When the process terminates, the port characteristics are not reset to their original values.

-d dataarg
This option allows stacking data for the process once it is activated. "dataarg" is any string which contains displayable characters and commands prefixed by a back slash (). Note that the string is subjected to the normal shell parsing, thus, back slashes must be "escaped", or the entire string must be enclosed in single quotes. "dataarg" can be contained in a Unix file by using the shell command substitution mechanism (e.g. using "back quoting" mechanism: -d ~` cat /usr/lib/pick/logon~`). All line feeds in the input string are converted to carriage returns.

The 'dataarg' commands are:

r Insert a carriage return.

f Turn echo off. The stacked data will not be displayed.

n Turn echo on. The stacked data will be displayed.

m Wait until the Pick virtual machine enters multiuser mode. The "maxusers" TCL command should be included in the "user-coldstart" macro after all system and application initialization are completed.

Insert a back slash.

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 logon sequence.

-l
Retains login Unix user-id. This option logs the process as the same Unix user as the one used to log in to Unix. This option overrides the user definition contained in the configuration file. A Pick process started with this option does not have access to the Pick spooler, nor to the message facility (or at least very restricted). The user is in some way isolated from the other Pick users. This option should be used only for users who want their own Unix environment underneath the Pick process or to do system configuration which requires 'root' access.

-D
Enables 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<return> to actually start the process.

-s
Enables "silent" mode. If used along with the "-0" command, the Pick machine will boot, and return directly to Unix. If used on a normal line, output of logon and logoff messages and user macros is suppressed and any attempt to logoff will return directly to Unix. Because output is supressed, the "-s" flag must generally be used along with the "-d" flag followed by a string containing the user name, user password, MD, and MD password when applicable so that the user is logged into Pick automatically. The "-s" flag is used by the "tcl" Unix shell script.

-i nice
Set the relative priority of the Pick process, compared to other processes, Pick or not, running on the system. Legal values of 'nice' are -20 to +19. -10 gives the highest priority, +19 the lowest.

-W
Wait for the device specified by the '-t' option to be created. Available only on AP 6.1.7 or later. This option instructs the Pick 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 (for example on HP-UX using a DTC). The process polls the specified device and waits until it is created as a pipe or block or character device. This option is ignored if the '-t' option is not specified as well.

-printer
This option specifies that the port is to be used as a printer. It suppresses the messages 'Connected to virtual machine',and 'Disconnected from virtual machine', but does not suppress the normal Pick processes messages, like the Pick logon message.

-pprinter
Parallel Printer. This option specifies that the port is to be used as a printer on a parallel device. This option must be used on Unix implementations where the device is a write-only device, such as in the case of AIX. If the parallel printer is a Read/Write device, this option is equivalent to "-printer".

-spooler
-scheduler
-phantom
Any of these three options specifies that the port is to be used as a phantom, or as a process not attached to a physical port.

-u /ttelnet.port,s
Starts AP telnet on telnet port telnet.port. This option starts the AP telnet server on the telnet port number specified by telnet.port and waits for connection from a client. The client makes the connection by using telnet on the server host and the same telnet.port.
Syntax ap {{-[0|a bootarg|port.number|f|q|k] }{-n configfile} {-t tty} {-y sttyarg} {-d dataarg} {-l} {-i nice} {-[printer|pprinter]}} {-D} {-s} {-W} {-u /ttelnet.port,s}
Options
Example
ap -0
Starts the virtual machine 'pick0' (default name).

ap -n mymachine -0
Starts the virtual machine 'mymachine'. 

ap
Starts a User process on the virtual machine 'pick0' (default name 
' '), on the first available port. (default PIB ' '). 

ap -5
Starts a User process on the virtual machine 'pick0' (default name 
'-'), on port 5. 

pick -n mymachine -7

Starts a User process on the virtual machine 'mymachine', on port 7. 

ap -q
Displays information about the virtual machine 'pick0' (default 
name). 

ap -0 -t tty2
Starts the virtual machine 0 on /dev/tty2. This statement is normally included 
in the /etc/inittab file. 

ap -3 -t tty6 -y "9600 parenb -parodd" -printer

Starts a user process on /dev/tty6 as a printer. It changes the baud rate to 
9600 baud and sets the parity to odd. This statement is normally included in 
the /etc/inittab file. 

ap -a a3x
Automatically boots the virtual machine, then does an ABS restore from device 
3, then issues an "x" option. 

ap -d 'rmdmracctrterm ibm3151rmenur'
Starts a user process on the first available port, stacking commands to wait 
until multiuser mode is entered, and then log it as "dm" on the 
account acct, executing the "term ibm3151" and "menu" 
commands. Note the first 'r' to make sure the process will be logged 
on properly the very first time after a boot.

Shell script 'boot.ap':
001 # Test if VM is active. else boot it
002 ap -q > /dev/null
003 if [ $? ! -eq 0 ]
004 then
005    -a x
006 fi

This shell script uses the -q option to test whether the virtual machine is 
booted or not. If the 'ap -q' command returns a null exit code (ok), 
then the virtual machine is already booted and nothing is done. Else the 
virtual machine is booted automatically.

$su 
password:(enter 'root' password)
$ap -l

Enters the Pick virtual machine, retaining the current Unix user id (root, 
because of 'su').

$ap -7 -u /t2007,s &

Starts a background AP telnet server process which connects to the default AP 
virtual machine "pick0" on PIB 5 and waits for connection from 
client.  If the server host name is serverhost,  a Unix client makes the 
connection by using the "telnet serverhost 2005" command in Unix 
shell.
Purpose
Related port.number
unix.pick0
tcl.pick
tcl.kill
pid
tcl.psr
virtual.machine
tcl.maxusers