Dovetailed Technologies

Name

cozcontrol — start/stop a durable connection to the Dataset Pipes subsystem on a target server

Synopsis

cozcontrol start [-t]  -ssh [ssh-options...] [user]@host
cozcontrol stop 
cozcontrol -v
cozcontrol -h
    

Description

The cozcontrol command starts and stops a durable connection to the Dataset Pipes subsystem on a target server.

When starting a durable session, the cozcontrol start command is executed over the specified SSH connection to the Dataset Pipes SSH server subsystem on the target server. The Dataset Pipes subsystem starts a socket server to listen and process commands. Subsequent commands (fromdsn, todsn, cozclient, etc) retrieve connection properties from cozcontrol, use this information to establish a socket connection to the socket server, and execute the command on the server. The durable session ends when the cozcontrol stop command is issued (or an inactivity timeout occurs on the server) causing the socket server to shutdown and ending the SSH connection.

Alternatively, the cozcontrol command can be started with a tunneled option (-t). In this case, the initial SSH connection is configured as a control master with local port forwarding. Subsequent Dataset Pipes commands are forwarded to the server over the SSH connection established by cozcontrol start.

In both modes, the SSH connection remains established until either a cozcontrol stop command is executed or an inactivity timeout on the server occurs.

A user may set up concurrent durable sessions to multiple user/host pairs; however, not multiple sessions to the same user/host pair. To identify which durable session to use, set the environment variable COZ_CONTROL_SESSION to user@host prior to executing Dataset Pipes and cozcontrol stop commands.

Options

start

Starts a durable connection to the Dataset Pipes subsystem on a target server.

The cozcontrol start process runs in the background until a stop command is issued. If the terminal running the start command ends, the cozcontrol start process and its child SSH process will continue to run until the timeout occurs in the z/OS dspipes subsystem. This timeout value is configurable in dspipes_config.

-t

Specifies that the cozcontrol durable connection be tunneled. In this case, the initial SSH connection is configured as a control master. Subsequent Dataset Pipes commands are forwarded over the SSH connection. The -t option is not set by default. When set, the environment variable COZ_CONTROL_PATH sets the control path. By default, the control path is ~/.ssh/cm-%r@%h:%p.sock. This option can only be spectified after the start keyword.

Notes:

  • OpenSSH 5.6 or later is required.

  • This option is not supported on Windows using cygwin and OpenSSH. See CYGWIN controlMaster connections don't work for the latest on this issue.

  • If the target SSH server is not running on port 22, either EXPORT COZ_CONTROL_PATH=~/.ssh/cm-%r@%h.sock (i.e. removing :%p from the default value) or add the port configuration for the target host in ~/.ssh/config. This issue will be fixed in a future release.

-ssh [ssh-options...] [user]@host

Specifies the ssh connection to the given z/OS user@host for the cozcontrol start command. This option is required and only permitted with the start keyword.

stop

Stops a durable connection to the Dataset Pipes subsystem on a target server.

-h

display help and exit.

-v

display the current version and exit.

Examples

Execute Dataset Pipes commands in a durable session

cozcontrol start -ssh user@host
fromdsn 'hlq.dsn' > /home/user/mydata/data1.txt
todsn 'hlq.dsn' < /home/user/mydata/data2.txt
cozclient wto "message to console"
cozcontrol stop

This example shows a durable session started for user@host. The next three commands (fromdsn, todsn, and cozclient) are executed over the socket connection established by cozcontrol start. Once the commands are complete, cozcontrol stop causes the socket connection to shutdown and the SSH connection to end.

Start a tunneled durable session

cozcontrol start -t -ssh user@host

Start a tunneled durable session for user@host. Subsequent Dataset Pipes commands are forwarded over the shared SSH connection established by cozcontrol start.

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.