tape-socket command

For Windows: Not Supported

Syntax 

tape-socket {cmd{keyword=value} {(options}}

Parameter(s)

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

The variable cmd represents one of these commands below (where allowed abbreviations are shown between parentheses):

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

Arguments

The arguments are specified by a series of statements keyword=value. Arguments can be specified in any order. If the value is a question mark, the user is asked to enter a value for the specified keyword, at which point a question mark, help, and q (quit) displays. If the value is a period, the value used last is substituted. These forms are used in macros where keyword is one of these specified arguments:

notify="dm,!0,exec run bp send-mail

Status Option

The status option lists this information:

Query command Result

The query command returns the running parameters and this information:

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 resynchronize 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. The chk.com command is executed by the remote input Server. If there is more than one word, it must be enclosed in single quotation marks (for example, cmd=’exec where 0 (h’):

System administrator messages

This lists the messages that can be sent to the D3 users designated in the notify parameter, the likely cause and the possible actions to correct the situation:

Communication to host is reestablished.

Indicates the output server succeeded in reestablishing the connection. This message is issued only once.

Input Server stopped due to an error.

Indicates 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, and so on.

Network Back On Line.

Indicates after a network error was detected, the communication was reestablished. This message is sent only once, to indicate the end of a problem.

Network Error. Check Error Log.

Indicates a network error was detected. Check the error log to see the cause of the failure. Check if the input server is up. Use the UNIX command ping<host> to verify the remote host can be reached. This message is sent only once, the first time an error is detected.

Network is disconnected. Retrying to call host.

Indicates the output server failed to establish or reestablish 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 verify the remote host can be reached.

Output Server stopped due to an error.

Indicates the server encountered a fatal error. Use the Status option to find the last error.

Transaction logger problem. Test item not sent.

Indicates 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 enqueueing 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 submenu.

Transaction logger problem. Lost poll.

Indicates 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 submenu.

Transaction log back on line.

Indicates 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

Indicates that the transaction logger was detached from the tape without the output server being notified. This was probably caused by using the transaction log menu instead of the tape-socket stop command or menu option. Stop the output server and restart it to correct this situation.

Transaction Restore not Restarted on Receiver.

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 means other than the tape-socket menu or command. If the tape has been detached manually from the transaction logger, which can be displayed 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 submenu 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 transaction log 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 (for example, Mount Next reel, or end if an abort occurred, and so on). Then, restart the input server. The pipe might have to be drained on the receiver’s side, using the Drain Pipe option in the Special Operations submenu.

Transaction Restore problem. diagnostics

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 probably requires 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 displays. 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.15)
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 submenu allows performing seldom used operations, for example, to test a new installation.

Network Tape (1.5.15) : 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 online help.

Hot Backup Setup

Assume a TCP/IP configuration over Ethernet, between two systems. The sender is the production system prod and the receiver a backup system backup. The two systems are to be set up in a hot backup configuration. Both systems are defined in the UNIX /etc/hosts/ file.

1. Create a pipe (from UNIX) by typing:

   mknod /dev/tapein p
   chmod a+rw /dev/tapein
   

2. Declare the pipe as a pseudo tape in the D3 configuration file of the receiver, by typing the statement:

   tape /dev/tapein 500 c lx
   

3. Boot the D3 virtual machine on the backup system. You must have at least two terminals connected to the backup systems. One is used for the transaction restore, and the second one is used, temporarily, for system administration.

4. 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.

5. Set the default Server by selecting the option Setup Server in the menu. Type:

   Server type : in
   TCP/IP port number : 3000
   Protocol : inet
   UNIX pipe name : /dev/tapein
   D3 User to notify : bob
   Start transaction logger : on
   

6. Start the input server on backup by selecting the option Start Server, or type:

   tape-socket start
   ’PROD’ setup:
   

7. Create a pipe (from UNIX) by typing:

   mknod /dev/tapeout p
   chmod a+rw /dev/tapeout
   

8. Declare the pipe as a pseudo tape in the D3 configuration file of the sender by typing:

   tape /dev/tapeout 500 c lx
   

9. Boot the D3 virtual machine on the prod system.

10. Set the default server by selecting the option Setup Server in the menu by typing:

    Server type : out
    Remote HOST name : BACKUP
    TCP/IP port number : 3000
    Protocol : inet
    UNIX pipe name : /dev/tapeout
    D3 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
    

11. Start the output server on prod by selecting the option Start Server, or by typing:

    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.

To check if the remote input server is active:

1. Select the Special Operation submenu, option Send command to Remote.

2. Type query to the question prompt cmd=, or, from TCL, use the check command. For example:

   tape-socket check cmd=query
   

   The input server responds with a short message. The check command can also be used to do some short commands on the remote input server. For example, to set the date on the remote input server enter:

   tape-socket check cmd="set-date 10/06/93"
   

   Note: Quotation marks are used around the command.

To stop 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.

To detach the tape on the master system:

1. Stop the transaction logger.

   This can be done without any human interaction on the backup system.

   Note: Do not use the transaction log menu to do this.

2. Select the tape-socket menu option Stop Server.

   This option detaches the tape from the transaction logger, makes the remote machine aware of the fact that the transaction logger is stopping temporarily, and stops the output server.

To reattach the tape to the transaction logger:

1. Restart the data transfer, again.

   Note: Do not use the transaction log menu to do this.

2. Select the tape-socket menu option Start Server.

   This option restarts the output server and the transaction logger process.

To detach the Tape on the Backup System:

This operation can 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:

1. 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.

2. Restart the output server on the main system.

   Note: 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 stops, even if the output server is still running.

Other usages

When not linked to the transaction logger subsystem, the tape-socket servers can be used for a variety of functions. Be sure the servers 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 disk. To achieve this, on the sender’s side, start the output server using the floppy disk device name instead of a pipe. For example, the output server starts reading from the floppy disk and writes its content over the network into the pipe on the receiver’s side, which it can then do a t-load. After the floppy disk has been sent, stop both servers. It does not handle multiple volumes.

• There is no obligation that the tape process and server be in the same D3 virtual machine. One application is to do full file restores across the network. To implement this, the receiver’s system should have a small D3 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 D3 virtual machine performing its file load.

kill -int p <pib.number>
kill -hup p <pib.number>

Troubleshooting

When a network is involved, there is a high probability that some incident will occur. When the transaction log test polling is activated, the output server periodically attempts to write a test item in a test file and controls the item is sent to the remote server. If not, the output server complains and sends a message to the D3 user specified by the notify argument. This topic describes the potential problems that occur and the procedures to recover them. These include:

• No data transfer takes place.

  List the status of the servers by using the List Status menu option. If one is stopped (a C in the S column), the server has encountered a fatal error and is terminated. A message displays specifying the cause of the error. This error must be corrected. A fatal error can be caused by any one of these factors:

  • An incorrect pipe name.

  • Does not have appropriate permissions.

  • The socket port number is already in use by another network application.

    If both servers are shown as Running, and if there is no error message in the trace (the last message is usually Started, Running, or TX LOG # OK), query both servers, using the option Query Server in the menu. The normal state is Open pipe if no tape process has opened the pipe yet, or Reading Network for the input server and Reading Pipe for the output server. Most likely, the output server displays Wait subsequent call, indicating it is trying to call the input server. To determine the cause of the failure, turn the trace on on the output server by selecting the option Turn Trace ON on Server on the sender’s side. After a few seconds, list the status. The traces indicate the cause of the failure by the value of errno, which can be found in /usr/include/sys/errno.h. After correcting the problem, turn the trace back off.

  • Network is disconnected.

    If both ndisc and callrep are set to 0, both servers wait indefinitely until the network is re-established. No data loss occurs. The tapes displays as not ready while the network is down. If one of these values is not null, then one or both of the servers may stop. They can be restarted when the network is back online. Be careful to restart the servers with the c option, so that the data which has been put into the pipes by the associated tape processes is not discarded.

  • Tape process on the receiver’s side is stopped.

    It is likely that there is data still in the pipe on the receiver’s side, in the network buffers and in the sender’s pipe. As a rule, to stop the whole process, stop the sender first, then stop the rec eiver. But if it was not the case, it is likely that some data loss will occur. First, try to restart the tape process on the receiver’s side. It is likely that it will complain, because it will expect some kind of a label. If it says First reel was unlabeled or Wrong reel number, type o and press ENTER to override. If it asks for the next reel, type c to continue, and then o to override the wrong reel message. If this is an account restore, it is likely to complain because of unexpected data. It may be necessary to skip segments until the process can be resynchronized.

    If all this fails, stop the input server on the receiver’s side and restart it with the c option, or use the menu option Start Server with No pipe clear, and retry. If this fails again, stop the output server on the sender’s side, stop the input server on the receiver’s side, stop both tape processes on the sender and receiver and restart the servers without the c option to purge the pipes and restart from a clean base. A significant amount of data can be lost. Data which purged from the pipe is stored into the file ts.log,backup. The item-IDs are numeric numbers. Each item is a 512-byte tape block (dumped in 2 ASCII hexadecimal numbers for each byte).

See also

%socket() function, Network save/restore, stoplog command, Tape socket, tlog-restore command, Tape socket, txlog command, txlog-status command, update-logging command