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.

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.

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

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.