tsocmd - Run a TSO/E command from the shell (including authorized commands)

Format

tsocmd TSO_command

Description

tsocmd runs a TSO/E command from the shell by using the TSO/E terminal monitor program (IKJEFT01). Unlike the tso command, the tsocmd command can be used to issue authorized TSO/E commands. (For more information about the tsocmd command, see tso - Run a TSO/E command from the shell). Because the TSO Terminal Monitor Program (TMP) is run in a separate address space and process from the tsocmd command, TSO/E commands that are issued do not affect the environment that the tsocmd is issued from.

For more information about the TSO/E TMP, see What is a command processor? in z/OS TSO/E Programming Guide.

Usage notes

  1. The BPXWRFD environment variable can be set to cause file descriptors to be inherited by the TSO command processor. See the description of environment variable BPXWRFD Environment variables for information about which file descriptors are inherited.
  2. Do not issue 'tsocmd output' from the OMVS shell. If you do, you might not receive any output.
  3. The standard input stream can also be queued as input to the TSO command. For example, if you have a file that is redirected as input and you run a TSO command before processing that file, some or all of the file can be queued to the TSO command. If input is the terminal, the queued input can be queued to the TSO command. This characteristic can be used to interact with some TSO commands. To prevent an abend while reading from SYSTSIN, the regular file allocated to STDIN (fd0) must have logical records that are at most 80 characters long.
  4. To prevent the standard input stream from being queued as input to the tsocmd command, use standard shell redirection notation to redirect STDIN to /dev/null. Example: 
    tsocmd time < /dev/null
    When the tsocmd command is in a shell script, it also processes the contents of STDIN (for the script), a line at a time. If the STDIN file is small, processing will continue even though the tsocmd command is processing each line of the STDIN file to TSO.

    If STDIN points to a very large file, a hang can occur if TSO passes back too many failures to fit in the pipe. By the time the STDIN file contents are fully processed, there are no readers left on the TSO output pipe because the command has already completed.

Examples

  1. To issue the authorized RACF® command RDEFINE, issue: 
    tsocmd "RDEFINE FACILITY BPX.FILEATTR.PROGCTL UACC(NONE)"
    Quotation marks are used around the command to avoid shell parsing.
  2. To use OGET to copy from a file in your current directory to an MVS™ data set, issue: 
    tsocmd "oget hello.c 'source.c(hello)'"
    Quotation marks are used around the command to avoid shell parsing.
  3. The examples in the tso command also apply to tsocmd where one replaces the string 'tso -t' with the string 'tsocmd'. See the examples in the tso command section (Examples) for more information.

Environment variables

Depending on the tsocmd command that is being issued, you might need to perform allocations or other customization for the TSO/E environment. These environment variables can be used:
BPXWRFD
Specifying YES in a REXX program before the TSO process is started causes the TSO process to inherit open file descriptors 10 through 99.

Specifying a numeric value in a REXX program before the TSO process is started causes the TSO process to inherit open file descriptors 10 through that numeric value. The maximum value that can be specified is limited by the setting of the system configuration (SYSCONF) value for OPEN_MAX. If a higher value is specified, then it is limited by OPEN_MAX. If a value less than 10 or a nonnumeric value other than YES is specified, then no additional file descriptors beginning at 10 are inherited.

SYSEXEC
Specifies the allocation specification for the SYSEXEC DD name. If the TSOALLOC variable is set, this variable is not automatically used.
SYSPROC
Specifies the allocation specification for the SYSPROC DD name. If the TSOALLOC variable is set, this variable is not automatically used.
TSOALLOC
Specifies the names of the environment variables that contain allocation specifications. The names are separated by colons. Case is respected; lowercase letters are treated as lowercase. The names of the environment variables also correspond to the name of the DD name to be allocated. The DD name is always treated as uppercase but the variable name can be specified in mixed case to avoid possible conflict with similar environment variable names.

The HOLD attribute is supported for SYSOUT allocation in the BPXWDYN text interface and TSOALLOC environment variable.

TSOPROFILE
Resets the profile with the arguments that you specify with the TSO/E command. (The specified arguments replace the default values.) For example, to set the TSO prefix and to turn off message IDs, issue: 
export TSOPROFILE="prefix(wjs) nomsgid"
The value of this variable is passed to the TSO/E PROFILE command as is. If the PROFILE command fails, the requested command is not run. The output from the PROFILE command is sent to stdout along with the PROFILE command that was issued.

An allocation specification can be either a list of cataloged data set names that are separated by colons or a data set allocation request. If a list of data set names is used, lowercase letters are treated as uppercase and the data set names must be fully qualified.

Specify a request for data set allocation by beginning the specification with the keyword alloc followed by keywords or keyword-value pairs in a format similar to the TSO/E ALLOCATE command. Keys are separated by blanks. A complete listing of keys can be found in Requesting dynamic allocation in z/OS Using REXX and z/OS UNIX System Services. You can also refer to the list of keys in the tso command description in tso.

Exit values

0
The TSO/E command was successful.
1-254
The TSO/E command ended in an error with the listed return code.
255
The TSO/E command ended with an unexpected error, the TSO/E command return code is outside the range 0-254, no command was entered, an error occurred when processing an environment variable, or the command was not found.

Localization

The tsocmd command is not sensitive to a user's locale. It is up to the user to provide input that is acceptable to TSO/E.

Related information

tso