tcl.tape-socket Verb: Access/TCL

tcl.tape-socket

Command tcl.tape-socket Verb: Access/TCL
Applicable release versions:
Category TCL (746)
Description defines a tape system across a network. This section is a detailed reference of the "tape-socket" TCL command. See the section "tape socket, General" for an introduction to the fundamental notions necessary to the set up and utilization of this system.
The "tape-socket" TCL command is used to create the input or output server and control their activity. A tape-socket log file "ts.log" is created the first time the command is started to record the process activity, and a permanent log "ts.log,log" keeps all messages.

This command can be executed only on the 'dm' or 'sysprog' account. It requires a SYS2 privilege.


Commands :

"cmd" is one of the following, where allowed abbreviation are shown between parenthesis:

check (ch) Check remote Server.
drain (dr) Drain (empty) pipe.
query (q) Query a server.
setarg () Change argument.
setup () Setup Server parameters.
show () Show Server parameters.
shutdown () Stop BOTH Servers.
start (ss) Start a server by name..
startsend (ss) Start the output server.
startreceive (sr) Start the input server.
status (sta) List the server status.
stop (sto) Stop a server.
stopall (stopa) Stop all servers.
traceon (tron) Turn traces on.
traceoff (troff) Turn traces off.

Without any argument, a menu is displayed, showing the most useful options to manage the default server. The menu is described later in this section.


Arguments :

The arguments are specified by a series of statements "keyword=value". Arguments can be specified in any order. If "value" is a question mark (?), the user is asked to enter a value for the specified keyword, at which point a question mark (?) will display some help and 'q' will quit. If "value" is a dot (.), the value used last time is substituted. These forms are used in macros.

"keyword" is one of the following:

callrep Number of attempts the output server will do to call the input server. After this number has been reached, and if the input server does not respond, the output server will terminate. '0' means infinite number of attempts to call. The default value is 0. A 5 second delay occurs between each attempt.

cmd Command to be executed on the remote system. See the list of valid commands below in the section "Check Command". This form is used to check the communication link. See the example section. Valid only on version 1.4.1 and later.

host Network name of the host where the input server resides. This argument is required only for the output server to be able to reach the input server. The host name must be defined in the '/etc/hosts' file in the sender.

ndisc Maximum number of network disconnection(s) either server will tolerate. A value of 0 means infinite number. When a network disconnection occurs, the output server will try to call the input server again. The default value is 0.

notify Name of one or more Pick user(s) to whom error messages are sent. The notify list may have one of the following forms:
OFF : Disable the notification.
user : Pick user name.
! line : Pick line number
* : All Pick users.
exec cmd : Run 'cmd'.

More than one user can be specified, by separating each user by a comma (eg notify=bob,sam). If the form 'cmd' is used, the entire notification list must be enclosed between quotes, because of the space which follows the 'exec' key word. For example, notify="dm,!0,exec run bp send-mail". The text of the error message is added after 'cmd'. The users must exist in the "dm,users," file. Valid only on version 1.5.0 and later.

pib Pick port number of the server. This option can be used as an argument to the "query" and "stop" commands as a quick alternative to the form "pipe=device".

pipe Define the Unix pipe. A full path name must be provided (eg /dev/tapein). The pipe MUST exist and have appropriate read/write permissions. A raw device device name will be accepted as well.

poll Defines the period with which the transaction logger is tested. "poll" is expressed in seconds, or in HH:MM:SS. A value of 0 disables the transaction log test polling. See the section "tape socket, General" for a detailed description of this feature. Valid only on version 1.5.0 and later.

port Socket port number in decimal of the input server on the receiver's side. The socket port number is a convention between the input and outputserver. It is a decimal number between 1024 and 32767.

prot Network protocol. The following protocols are supported:
"inet" : Internet.

server Name of the server. If left empty, the default server is used. The Server name can be any string. Valid only on version 1.5.0 and later.

servertype Type of the server. This option is required when using the "setup" command to set up the running parameters of a Server. "servertype" is either 'IN' for the Input Server, or 'OUT' for the Output Server. Valid only on version 1.5.0 and later.

trace Maximum number of traces either server will keep in the log file. The default value is 4. Without the (V) (verbose) option, only major events are recorded. The (V) option records ALL data. When this number is exceeded, the oldest trace entries are discarded.

txlog Specify whether the Server is to be linked automatically to the Transaction Logger. "txlog" is either 'ON', or 'OFF'. See the section "tape socket, General" for a detailed description of this feature. Valid only on version 1.5.0 and later.

txopt Specify whether the Transaction Logger should log updates to all files, or only to files with the (DL) attribute. This option is valid only for the Output Server, if 'txlog=ON'. 'txopt' is either 'DL' or 'ALL'. Valid only on version 1.5.0 and later.

txpriod Specify the period, in seconds, with which the transaction log queue is emptied. A value of 0 specifies the default value. Valid only on version 1.5.0 and later. On AP versions prior to 6.1, this time cannot be changed and must be specified as 0.


Status Command :

The "status" commands lists the following information:
id Port number of the server, in decimal.

T Type of the server:
s : Send (output) server
r : Receive (input) server

Pipe Pipe name

Host Host name (input server only).

Port Socket port number in decimal

S Status of the server;
E : Error
C : Completed
L : Logoff
Q : Queued
R : Running
S : Aborted

Time Time of the last trace entry

Date Date of the last trace entry

Message Trace message. Each trace is prefixed by the current message number in decimal. The servers exchange message number information to make sure no data loss occurs. The following are the main messages:

ACK timeout The input server did not respond to a message. The output server retries.

Accept err=n accept() system call error. n=errno.

Bad header 'X' A network message had an incorrectly formatted header. 'X' is a hex dump of the header.

Bad msg num 'X' A network header contained an incorrect message number 'X'

Bind err=n Input server could not 'bind' with the specified port. n=errno.

Broken pipe Input server tried to write into pipe, but associated tape process detached from it.

Call err=n Output server can not call input server. n=errno.

Cannot find jobid Server could not find its job id in the phantom log files 'jobs'.

Check ERR The input Server responded to a 'check' command but found an error.

Check OK The Input Server responded to a 'check' command.

Clear pipe Clear the pipe, if NO (C) option.

Connect accept The input server accepted an incoming connection.

Connect err=n Output server failed to establish connection. n=errno.

Hread trunc=n Network msg header truncated. n=msg length.

Listen err=n listen() system call error. n=errno.

Local query Server responded to a 'tape-status query' command.

Lost msg=n Input server detected a message loss. n is the message received. Messages from the current message up to n are lost.

Lost POLL n A Transaction Log test item has not been received by the Input Server.

Malloc err=n malloc() system call error. n=errno. Server could not obtain memory for buffers.

Nread err=n Network read error. n=errno.

Nread n xxxxx Network read. n=msg length, 'xxxxx' trace.

Nwrit err=n Network write error. n=errno.

Nwrit n xxxxx Network write. n=msg length, 'xxxxx' trace.

Nwrit trunc=n Network write truncated. n=msg length.

Open pipe Wait for pipe open.

Pclear err=n Error while attempting to purge the pipe. n=errno.

PEOF err=n Input server failed to write a EOF marker in the pipe.

Popen err=n open() pipe error. n=errno.

Pread err=n Pipe read error. n=errno.

Pread n xxxxx Pipe read. n=msg length, 'xxxxx' trace.

Pread trunc=n Pipe read truncated. n=msg length.

Pwrit err=n Pipe write error. n=errno.

Pwrit n xxxxx Pipe write. n=msg length, 'xxxxx' trace.

Pwrit trunc=n Pipe write truncated. n=msg length.

Re-sync n Input server receives a SYNC message from output server. n=new starting msg number.

Send resync Output server was asked to send a sync message.

Remote shtdwn The Input Serer receives a request to stop.

Running Server is running. This status is stored every 5 mn on a busy system. This message is not stored in the permanent log.

Sent POLL A Transaction log test item has been sent to the Input Server.

Seq error n An message was received twice. n=old message number. The msg is discarded.

Started Server is started.

Stop on req Server stopped due to a 'tape-socket stop' command.

Stop refused-Txlog up A request to stop the input server was refused because the transaction logger is still active. Repeat the stop request.

Stopped Server is stopped due a spontaneous termination. The cause of the termination is indicated in a previous trace entry.

Socket err=n socket() system call error. n=errno.

TLOG not off The Input Server failed to abort the transaction restore process following a request to stop.

TLOG Restarted The Input Server restarted the transaction restore process following a request from the remote Output Server.

TLOG Terminated The Input Server aborted the transaction restore process following a request to stop.

Too many disc Server detected disconnects in excess of 'ndisc' and terminated.

Too many errors Server detected too many errors

Total on dd/mm Total number of kilobytes transferred since the first time a message was logged the morning of the specified day.

Txlog OK Transaction log test item has been received by Input Server. This message is not stored in the permanent log.

Unexpected msg 'X' The message 'X' on the network is not a 'tape-socket' msg.

Unknown cmd 'X' Server received an unknown command 'X'

Wait ack Output server is waiting for an ACK.

Wait connect Input server waits for incoming call.


Query Command Result :

The "query" command returns the running parameters, and the following information:

Next poll time Time, if activated, of the next Transaction Log test polling.

Total Data transferred Total number of kilobytes transferred that day. This number is approximate.

Last msgnum Last message number, at the time of the last query and the average number of messages per second since the last query. This count does not include the protocol message.

msgin Total number of messages input to the server. For an input server, this is the number of network messages, including the protocol messages. For an output server, this is the number of tape blocks read from the pipe.

msgout Total number of messages output from the server. For an input server, this is the number of tape blocks written into the pipe. For an output server, this is the number of messages sent on the newtork, including the protocol messages.

curmsg Current message number. During normal operations, the values of 'curmsg' for both servers should be equal. Should they diverge, the input server will log the incident and re-synchronize.

Status Short description of the server current status:
Open pipe
The server is waiting for the associated tape process to open the pipe. This is the quiescent state of both servers when no tape process has opened the associated pipe.

Reading network
The input server is waiting for incoming data from the network. This is the quiescent state of the input server.

Reading pipe
The output server is waiting for data from the associated tape process. This is the quiescent state of the output server.

Wait 1st call
The output server is waiting for the answer to its first call to establish connection. Wait incoming connect. The input server is waiting for an incoming call.

Wait subsequent call
The output server is waiting for the answer to repeated call(s) to establish connection. This is an indication of failure to establish communication with the input server.

Stopped
The server is stopped.


Drain Command :

The "drain" command empties the specified pipe. This command is implicitly executed when starting a server, unless the (C) option is specified or if the Server is linked to the Transaction Logger. Emptying the pipe is sometimes necessary to re-synchronize the processes. The data which is drained out is saved in the file "ts.log,backup" for later processing.


Check Command :

The "check" command is used to send requests from the local Output Server to the remote Input Server. The main purpose is to check the communication link and to do some remote control of the input server. "chk.com" is the command to be executed by the remote input Server. If there is more than one word, it must be enclosed in quotes (eg cmd='exec where 0 (h'):

exec tcl.com Execute the TCL command 'tcl.com' on the remote. This command should a simple one, like 'who' or 'time'. Only the first line of the result is returned.

msgnum Returns the last message number received by the Input Server.

query Query the remote Input Server for its status.

shtdwn Shutdown Input Server. The Input server terminates immediately. If it is linked to the Transaction Log Sub-System, the transaction restore process is aborted and sent back the tape-socket menu. Valid only on version 1.5.0 and later.

test -f fn Test if the file 'fn' exists. If so, a string "1 File 'fn' exists" is sent back. Else a string "0 File 'fn' missing" is sent back. Valid only on version 1.5.0 and later.

test -r{d} fn id Test if the file 'fn' exists, and if the item 'id' is in this file. If so, a string "1 <item body>" is sent back. Else a string "0 File 'fn' missing" or "0 Item 'id' missing" is sent back. If the 'd' flag is present, the item is deleted. Valid only on version 1.5.0 and later.

tlchk Check the Transaction restore on the backup system. Valid only if the Input Server is linked to the Transaction Log Sub-System. Valid only on version 1.5.4 and later. This command makes sure the process doing the transaction restore is in a 'normal' state (attached to the tape, not waiting for input, not in the debugger, etc..), and will make some attempt at correcting the problem (answering to the prompts). This command is executed automatically by the Output Server when a transaction log polling test fails, and by the input Server if it appears that the transaction restore is not emptying the pipe.

tlstrt Restart the Transaction restore on the backup system. Valid only if the Input Server is linked to the Transaction Log Sub-System. Valid only on version 1.5.0 and later.

tron n Turn traces on on the remote. 'n' is the number of traces.

troff Turn traces off on the remote.


System Administrator Messages :

This section lists the messages that may be sent to the Pick users designated in the "notify" parameter, the likely cause and the possible actions to correct the situation:

Communication to host is re-established.
The Output Server succeeded in re-establishing the connection. This message is issued only once.

Input Server stopped due to an error.
The Server encountered a fatal error. Use the "Status" command on the receiver's side to find the last error. This is likely to be due to a serious condition like, the Unix pipe does not exist, or does not have the proper access rights, the TCP port number is already in use, etc...

Network Back On Line.
After a network error was detected, the communication was re-established. This message is sent only once, to indicate the end of a problem.

Network Error. Check Error Log.
A network error was detected. Check the error log to see the cause of the failure. Check the Input Server is up. Use the Unix command "ping <host>" to make sure the remote host is reachable. This message is sent only once, the first time an error is detected.

Network is disconnected. Re-trying to call host
The Output Server failed to establish or re-establish the connection after three attempts. This message is issued only once. Check the error log to see the cause of the failure. Check the Input Server is up. Use the Unix command "ping <host>" to make sure the remote host is reachable.

Output Server stopped due to an error.
The Server encountered a fatal error. Use the "Status" command to find the last error.

Transaction logger problem. Test item not sent.
The Output Server found that none of the Transaction Log Test items reached the remote system. Make sure the communication is up and that the enqueuing of transactions is active. If the transaction log queue is large, it may be because the test items are still in it. If the queue is empty or small, check the transaction logger with the TCL command "txlog". This message is likely to be an indication of a serious problem. This message is issued at every failed attempt until a test succeeds. If this becomes a nuisance, change the polling period, using the menu option "Change TX LOG Polling", in the "Special Operations" sub-menu.

Transaction logger problem. Lost poll.
The Output Server found that one of the Transaction Log Test items did not reach the remote system, even though some test items made it on the other system. This is likely to be a temporary condition, due to a large queue. This message is issued at every failed attempt until a test succeeds. If this becomes a nuisance, change the polling period, using the menu option "Change TX LOG Polling", in the "Special Operations" sub-menu.

Transaction log back on line.
The Transaction Log Test polling resumed its normal operations after an incident was discovered in a previous test. This message is issued only once to indicate the end of the problem.

Transaction logger not attached to tape
This message indicates that the transaction logger was detached from the tape without the Output Server being notified. This was probably caused by using the "txlog" menu instead of the "tape-socket" stop command or menu option. Stop the Output Server and re-start it to correct this situation.

Transaction Restore not Re-Started on Receiver.
This message indicates that the Input Server failed to restart the transaction restore. The process doing the Transaction Restore on the receiver is probably waiting for a user prompt due, most likely, to the stopping of the transaction logger by a mean other than the "tape-socket" menu or command. If the tape has been detached manually from the transaction logger, which can be shown by the "txlog" command, it might be possible to restart the transaction logger from the MASTER system, by selecting the option "Send Command to Remote" in the sub-menu "Special Operations", and send the command "tlstrt" which instructs the Input Server to restart the transaction restore. If this remote command succeeds, then reattach the tape to the transaction logger on the sender side by using the "txlog" menu. If this fails, the System Administrator must act on the receiver's side, by answering whatever question is asked on the transaction restore process (eg "Mount Next reel", or "end" if an abort occurred, etc...). Then re-start the Input Server. The pipe might have to be drained on the receiver's side, using the "Drain Pipe" option in the "Special Operations" sub-menu.

Transaction Restore problem. diagnostics
This message indicates that the Transaction Restore, on the receiving side, is in an abnormal state. This message is issued by the Output Server when, after having detected that a transaction polling test failed, an attempt at correcting the situation failed. This situation will probably require the System Administrator to intervene on the backup system (or use the remote command execution to act on the transaction restore).


Default Server Menus :

Without any option, a menu is displayed. This menu allows operations on the default Server. All optional arguments are set to their defaults, when using the menu. This should suit most configurations where there is only one server, either input or output. When an argument is missing, the user is prompted for it.

Network Tape (1.5.0)

1) List Status 4) Stop Server 7) Show Server
2) Query Server 5) Special Operations 8) Shutdown
3) Start Server 6) Setup Server 9) Other Servers


The "Special Operations" sub-menu allows performing seldom used operations, to test a new installation, for instance.

Network Tape (1.5.0) : Special Operations

1) Turn Trace ON on Server 7) Start Server with NO clear
2) Turn Trace OFF on Server 8) List Permanent Log
3) Change TX LOG polling 9) Clear Permanent Log
4) Change notify user 10) Test transaction Log
5) Drain Pipe 11) List pipes
6) Send Command to Remote

Each option in the menu has some on-line help. See the example below for how to use the menu.
Syntax tape-socket {cmd {keyword=value} {(options}}
Options C Do NOT clear the pipes before starting a server. This option should be used only if data in the pipe should be preserved. This situation normally arises only when the server is stopped in the middle of a communication. Extreme care should be taken when using this option.

Q Quiet. Suppress some user messages and confirmation prompts when stopping servers and draining pipes.

R Show only 'Running' servers in the "status" command

S Suppress the synchronization of clocks at startup time. Valid only on version 1.5.0 and later.

V Verbose. Record all events in the log file.
Example
Hot Backup Setup Example :
Assume a TCP/IP configuration over Ethernet, between two systems. The sender is 
the production system 'PROD' and the receiver a back up system 
'BACKUP'. The two systems are to be setup in a 'hot backup' 
configuration. Both systems are defined in the Unix '/etc/hosts/ file.

'BACKUP' setup:

  - Create a pipe (from Unix):
    mknod /dev/tapein p
    chmod a+rw /dev/tapein

  - Declare the pipe as a pseudo tape in the Pick configuration file of the 
receiver, by inserting the statement:
    tape /dev/tapein 500 c lx

  - Boot the Pick virtual machine on the 'BACKUP' system. You MUST 
have at least TWO terminals connected to the 'BACKUP' systems. One is 
going to be used for the transaction restore, and the second one will be used, 
temporarily, for system administration.

  - Select an unused TCP port number. The list of currently used  port numbers 
can be found, usually, in the Unix file "/etc/services", or by using 
the "netstat -a" command. The number can be anything (>1024 and 
<32767), as long as both servers agree on it. This example uses 3000.

  - Set the default Server by selecting the option 'Setup Server' in 
the menu. Enter the following:
    Server type : in
    TCP/IP port number : 3000
    Protocol : inet
    Unix pipe name : /dev/tapein
    Pick User to notify : bob
    Start transaction logger : on

  - Start the input server on 'BACKUP' by selecting the option 
"Start Server", or by typing, at TCL:
    tape-socket start


'PROD' setup:

  - Create a pipe (from Unix):
    mknod /dev/tapeout p
    chmod a+rw /dev/tapeout

  - Declare the pipe as a pseudo tape in the Pick configuration file of sender, 
by inserting the statement:
    tape /dev/tapeout 500 c lx

  - Boot the Pick virtual machine on the 'PROD' system.

  - Set the default Server by selecting the option 'Setup Server' in 
the menu. Enter the following:
    Server type : out
    Remote HOST name : BACKUP
    TCP/IP port number : 3000
    Protocol : inet
    Unix pipe name : /dev/tapeout
    Pick User to notify : bob
    Transaction Log test polling : 00:10:00
    Start transaction logger : on
    Log (DL) files or ALL : dl
    Transaction log queue period : 3

  - Start the output server on 'PROD' by selecting the option 
"Start Server", or by typing, at TCL:
    tape-socket start

On both systems, list the server activity by selecting the option "List 
Status". Both servers should show a status 'Started'. Query the 
servers by selecting option "Query Server". The Output Server should 
show a status "Reading Pipe" and the Input Server should show a 
status "reading Network". If not, refer to the section 
'Troubleshooting' below.

To check the remote Input Server is active, select the "Special 
Operation" sub-menu, option "Send command to Remote" and, in 
answer to the question "cmd=", type 'query', or, from TCL, 
use the 'check' command:
  tape-socket check cmd=query

The input server should respond with a short message. The 'check' 
command can also be used to do some short commands on the remote input server. 
For instance, to set the date on the remote Input Server (note the usage of 
quotes around the command):
  tape-socket check cmd="set-date 10/06/93"

Stopping a Server :
When attempting to stop a server, a warning is issued if the pipe served by 
this process is not empty. Unless absolutely required, it is not recommended to 
stop the server while data is in the pipe. In addition to this control, 
stopping the Input Server while the Output Server has not been stopped, will 
also issue a warning if the server has been linked to the transaction restore.

Detaching the Tape on the Master system :
On releases prior to 6.1, to be able to use the tape on the master system, it 
is necessary to stop the Transaction Logger. This can be done without any human 
interaction on the backup system. Do NOT use the "txlog" menu to do 
this. Select the tape-socket menu option "Stop Server". This command 
will detach the tape from the transaction logger, make the remote machine aware 
of the fact that the transaction logger is stopping temporarily, and stop the 
Output Server.
To re-attach the tape to the Transaction Logger and restart the data transfer, 
again,  do NOT use the "txlog" menu to do this. Select the 
tape-socket menu option "Start Server". The option will restart the 
Output Server and the Transaction logger process.

Detaching the Tape on the Backup System :
This operation should also be done from the MASTER system, to make sure all 
operations are done in the proper order. It involves stopping the transaction 
logger on the master system, stopping the transaction restore on the backup 
system, and then stopping the Servers. All this is accomplished by the 
'Shutdown" menu option on the MASTER system. After the remote 
shutdown has completed, the process which was doing the transaction restore is 
sent back to the tape-socket menu, after having detached the tape on the backup 
system. The tape can then be used.
To restart the system, first restart the Input Server. Remember that by 
starting the Input Server linked to the Transaction Restore, the process on 
which the "Start Server" menu option is run, BECOMES the process 
which does the transaction restore, thus not freeing the terminal. Then restart 
the Output Server on the Main system.
Note that if it is attempted to stop the Input Server without first stopping 
the Output Server, the Input Server will complain. If the stop command is 
repeated, then the Input Server will stop, even if the Output Server is still 
running.

Other usages :
When not linked to the Transaction Logger Sub-System, the tape-socket Servers 
can be used for a variety of functions. Be sure the Server are setup so that 
they are NOT linked to the Transaction Logger by using the "Setup 
Server" menu option.

- The 'tape-socket' command can also be used to provide remote access 
to a floppy. To achieve this, on the sender's side, start the output 
server using the floppy device name instead of a pipe. The output server will 
start reading from the floppy and write its content over the network into the 
pipe on the receiver's side, which can then do a T-LOAD, for example. 
After the floppy has been sent, stop both servers. It will not handle multiple 
volumes. 

- There is no obligation that the tape process and server be in the same Pick 
virtual machine. One application is to do full file restores across the 
network. To implement this, the receiver's system should have a small Pick 
virtual machine, in which the input server is running. The data it receives 
from the network (the file save), is written into the pipe which is read by the 
real Pick virtual machine doing its file load.
Purpose
Related basic.%socket
tcl.txlog
transaction.logger
tcl.stoplog
tcl.txlog-status
tcl.update-logging
general.tape-socket
tcl.tlog-restore
general.network.save/restore