Syntax

exec {logical-name | host-name} {cmd=command | cmdref=command-ref | stc=started-task} [user=userid] [pwd=password] [port=port] [codepage=codepage] [file=filename | xfile=filename [key=key]] [option=option] [mergelog=yes|no] [trace=yes|no] [input=data-element] [svropt=server-options] [stdout=data-element] [stderr=data-element]

Description

The exec command executes system commands on remote machines if you have Universal Command (UCMD) Manager on the same system with the UDM Manager.

The first parameter of the exec command is either:

logical-name (logical name) of a transfer server (valid only if a transfer session has been established)
host-name (Host name) of the machine on which you want to execute the command.

Note

You must have the UCMD Server and Universal Broker installed on the machine on which the command is to be executed.

The second parameter is the command type, which is either:

cmd (command)
cmdref (command reference)
stc (started task)

For any of these three types, the value (command) is the remote command to be executed. (See the Universal Command 7.7.x Reference Guide for more information about command types.)

UDM must authenticate a user on the remote machine in order to execute a command.

If a logical name is specified in the first parameter, the user and pwd values are inherited from the same options specified in the open command for that logical name. These inherited values can be overridden by specifying them explicitly in the exec command.
If a host name is specified in the first parameter, the user and pwd values must be specified explicitly in the exec command.

The port and codepage values are inherited from the UDM Manager's configuration file unless overridden explicitly in the call to the exec command.

port specifies which port the Universal Broker is listening on for the remote machine.
codepage specifies to which codepage the output of the remote command is translated.

The user, pwd, port, and codepage parameters can be stored in an external file instead of being specified explicitly in the exec command.

If a plain text file is used, use the file parameter to specify the name of this file.
If the file was encrypted with Universal Encrypt, use the xfile parameter to specify the name of this file.

If an encryption key other than the Universal Encrypt default was used, specify that key with the key parameter.

These parameters, and the format of the file containing these parameters, work exactly like the corresponding option in the open command.

The option parameter is used to pass options to the UCMD Server (see the SCRIPT_OPTIONS option for UCMD Manager in the Universal Command Reference Guide for more details).

Two streams of data come back from the remote command. By default, output from standard out and standard error of the remote command are written to standard out and standard error by the UDM Manager (SYSPRINT and SYSOUT, respectively, under z/OS). The mergelog parameter can be set to yes if you want both output streams written to the UDM transaction log (standard out under UNIX, Windows, and IBM i; SYSPRINT under z/OS).

By default, if the UDM Manager is invoked with tracing turned on, tracing will be turned on in the Universal Command Manager when UDM invokes it via the exec command. Likewise, if trace is turned off in the UDM Manager, the Universal Command Manager is invoked with tracing turned off. You can override this behavior for the UCMD Manager invocation by setting the trace option in the call to the exec command.

There are some commands that require input from standard input. To provide this input, you must create a data element with the data command containing the input. Specifying the name of the data element with the input parameter will cause the information in the data element to be sent over as standard input to the remote command.

The svropt parameter can be used to override UCMD Server options.

Note

UDM does not require a space before the server options, as does Universal Command.

The stdout and stderr parameters specify data elements to contain standard out and standard error, respectively, from the remote command. If the data elements do not exist, they are created. If the data elements do exist, they are overwritten with the output from the remote command. If the value portion refers to an existing non-data element variable or the name of a built-in variable (that is, any variable beginning with an underscore), an error is issued.

The exec command output will still be written to UDM stdout (the transaction log) and UDM stderr, where appropriate, even with the presence of the stdout and/or stderr.

Parameters

Parameter	Description
logical-name	Logical name of a transfer server as specified in the open statement (valid only if a transfer session has been established) of the machine on which you want to execute the command. Note You must have the Universal Command Server and Universal Broker installed on the machine on which the command is to be executed.
host-name	Host name of the machine you wish to execute the command on. Note You must have the Universal Command Server and Universal Broker installed on the machine on which the command is to be executed.
cmd=command	Command type cmd (command) will be executed on the remote server with its value being the command to be executed. (See the Universal Command 7.7.x Reference Guide for more information about available command types for each platform.)
cmdref=command-ref	Command type cmdref (command reference) will be executed on the remote server with its value being the command reference to be executed. (See the Universal Command 7.7.x Reference Guide for more information about available command types for each platform.)
stc=started-task	Command type stc (started task) will be executed on the remote server with its value being the started task to be executed. (See the Universal Command 7.7.x Reference Guide for more information about available command types for each platform.)
user=user-id	User ID (user) and password (pwd) are inherited from the same parameters specified in the open command for that logical name. These values can be overridden by specifying them explicitly in the exec command. Note If a host name is used (instead of a logical name), a user ID and password must be specified explicitly in the exec command.
pwd=password	User ID (user) and password (pwd) options are inherited from the same options specified in the open command for that logical name. These values can be overridden by specifying them explicitly in the exec command. Note If a host name is given (instead of a logical name), a user ID and password must be specified explicitly in the exec command.
port=port	Port that the Universal Broker is listening on for the remote machine. The port is inherited from the UDM Manager's configuration file unless explicitly overridden in the call to the exec command.
codepage=codepage	Codepage to which the remote command output is translated. The codepage is inherited from the UDM Manager's configuration file unless overridden explicitly in the call to the exec command.
file=filename	Plain text file containing the values for the remote execution server: port, user, pwd, and codepage. Note These values override any corresponding values specified for the transfer server in the open command.
xfile=filename	Universal Encrypted text file containing the values for the remote execution server: port, user, pwd, and codepage. Note These values override any corresponding values specified for the transfer server in the open command.
key=key	Key used to decrypt the file specified by the xfile parameter. If this parameter is not present, the default key for Universal Encrypt is used.
option=option	Passes options to the Universal Command Server.
mergelog=yes \| no	Specification for whether or not to merge the two streams of data that come back from the remote command to the UDM transaction log (SYSOUT under UNIX, Windows, and IBM i; SYSPRINT under z/OS). By default, output from standard out and standard error of the remote command are written to standard out and standard error by the UDM Manager (SYSPRINT and SYSOUT, respectively, under z/OS). Default is no.
trace=yes \| no	Overrides the trace behavior of the Universal Command Manager when invoked via the exec command. Default is trace value of the UDM Manager.
input=data-element	Data element to be used as standard input to the remote command.
svropt=server-options	Overrides Universal Command Server options.
stdout=data-element	Data element to be used as standard out from the remote command.
stderr=data-element	Data element to be used as standard error from the remote command.

Return Values

When the exec command is invoked, the return value from the exec command indicates whether or not UDM was able to invoke the remote command. The return value from the exec command will be 0 (none) if the remote command was invoked.

Upon successful invocation of the remote command, it might be useful to have the return value of the remote command itself in addition to whether or not the remote command could be executed. The remote command's return value is stored in the _execrc built-in variable.

The return code indicating whether or not the remote command could be executed is placed in _rc.

Use the following script snippet (or something similar) to exit based on a comparison of _execrc to _halton:

exec cmd ...
if $(_execrc) GE $(_halton)
   set _rc=$(_execrc)
   exit
end

(See Remote Execution Requirements for more detailed information.)

exec Command Examples

The following example uses the exec command to execute a simple directory listing on a Windows machine that is part of a transfer session:

exec winmachine cmd="dir c:\"

The following example uses the exec command to invoke a started task:

exec mvsmachine stc="mytask,parm=$(TASK_PARM)"

The following example calls the exec command that uses a data element for input to the remote command:

# Define the data element
 
data shellinput
  echo "Comparing $(_file) with $(_file).old:"
  diff $(_file) $(_file).old
  exit
end

# Rename all existing files on the destination

forfiles dst=*
  rename dst $(_file) $(_file).old
end

# Copy the new files over and compare them*

forfiles src=*
  copy src=$(_file)
  exec dst cmd="sh" input=shellinput*
end

Additional Information and Examples

For additional exec command information and examples, see Universal Data Mover - Remote Execution.

Browser not supported