tso - Run a TSO/E command from the shell

Format

tso [-o] [-t] TSO_command

Description

tso runs a TSO/E command from the shell using the TSO/E service routine or the OMVS interface.

Restriction: The tso command cannot be used to issue authorized TSO commands when the TSO/E command service is used. See tsocmd - Run a TSO/E command from the shell (including authorized commands) if that is required.

Options

-o: Specifies that the command be issued through the OMVS interface.
-t: Specifies that the command be issued through the TSO/E service routine. If a mini-TSO/E environment is to be established, use environment variables to specify the allocations that you need. Because the tso command uses an exec() of itself to clean up at completion, the tso command must be run with a valid PATH environment variable or be run with its full path name, /bin/tso.

If you do not specify an option, the following rules determine how to run the TSO/E command:

If stdout is not a tty, the TSO/E service routine is used because it is possible that the command output will be redirected to a file or piped to another command.
If the controlling tty supports 3270 passthrough mode, the OMVS interface is used.
If neither rule is applicable, then the TSO/E service routine is used.

Examples

To use OPUT to copy an MVS™ data set to a file in your current directory, issue:
```
tso -t "oput 'source.c(hello)' 'hello.c' "
```
If you do not specify -t, the command is run in your TSO/E session through OMVS, if possible. This copies the file to a file relative to the working directory of your TSO/E session, which is typically your home directory.

Quotation marks are used around the command to avoid shell parsing.

To use OPUTX to copy all members of a PDS to your current directory, issue:

tso -t "oputx source.c . lc suffix(c)"

If you do not specify the -t option, the command is run in your TSO/E session through OMVS, if possible. This copies the file to a file relative to the working directory of your TSO/E session, which is typically your home directory.

Quotations are used around the command to avoid shell parsing.

Because OPUTX uses ISPF, allocations for the ISPF DD names must be performed to run this command. The following is an example of the environment variables that are set to perform these allocations. This can be included in your .profile for convenience. Make sure the export statements start in column one. The data set names might differ on your system.

# Assign the DD names to allocate
#
export TSOALLOC=ispprof:ispplib:ispmlib:isptlib:ispllib:ispslib:\
isptabl:isplog:sysexec
#
# Allocate an empty, temporary ISPF profile data set
#
export ispprof="alloc new unit(sysvio) space(1,1) cyl dir(5) \
recfm(f,b) lrecl(80) blksize(3120)"
#
# Allocate an empty, temporary ISPF table data set
#
export isptabl="alloc new unit(sysvio) space(1,1) cyl dir(5) \
recfm(f,b) lrecl(80) blksize(3120)"
#
# Allocate the ISPF log to SYSOUT
#
export isplog="alloc sysout(a) recfm(v,a) lrecl(125) blksize(129)"
#
# Allocate the OpenMVS and ISPF panel data sets to ISPPLIB
#
export ispplib=SYS1.SBPXPENU:SYS1.ISP.SISPPENU
#
# Allocate the OpenMVS and ISPF message data sets to ISPMLIB
#
export ispmlib=SYS1.SBPXMENU:SYS1.ISP.SISPMENU
#
# Allocate the ISPF table data set to ISPTLIB
#
export isptlib=SYS1.ISP.SISPTENU
#
# Allocate the ISPF skeleton data set to ISPSLIB
#
export ispslib=SYS1.ISP.SISPSENU
#
# Allocate any load library to ISPLLIB if ISPF is in LINKLIST/LPA
#
export ispllib=SYS1.LINKLIB
#
# Allocate the OpenMVS EXEC data set to SYSEXEC
#
export sysexec=SYS1.SBPXEXEC

Environment variables

If the tso command is to be run through the TSO/E service routine, you might need to perform allocations or other customization for the TSO/E environment. These tasks can be specified using environment variables. You can use the following environment variables:

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.

TSOOUT or tsoout

Specifies the allocation attributes for SYSTSPRT. The format of the variable is in bpxwdyn format without a dd name. For example:

export tsoout="alloc path('/dev/tty') pathopts(owronly) filedata(text)"

If both TSOOUT and tsoout are used, TSOOUT takes precedence.

TSOPREFIX

Specifies a prefix for temporary data sets that need to be cataloged. Lowercase letters are treated as uppercase letters. If you do not specify this variable, the user's login name (user ID) is used.

TSOPROFILE

Resets the profile with the arguments that you specify when running 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 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 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. Following is a list of keys:

DA (data set name [(member name)]) | DSN (data set name [(member name)]): Data set name to allocate. The name must be fully qualified and can include a member name. Quotation marks can be used but are ignored.
MOD | NEW | OLD | SHR: Specifies the status of the data set.
CATALOG | DELETE | KEEP | UNCATALOG: Specifies the data set disposition.
TRACKS: Specifies that space be allocated in units of tracks.
CYL: Specifies that space be allocated in units of cylinders.
DIR(directory blocks): Specifies the number of directory blocks.
SPACE(primary[,secondary]): Specifies that primary and (optionally) secondary space be allocated.
VOL(volume serial): Specifies the VOLSER.
UNIT(unit name): Specifies the unit name, device type, or unit address.
SYSOUT[(class)]: Specifies that a sysout data set is to be allocated and optionally defines the output class.
HOLD: Specifies that the output data is to be held until released by user or operator.
WRITER(external writer name): Specifies the external writer.
FORMS(forms name name): Specifies the print form.
DEST(destination): Specifies the output destination.
COPIES(number of copies): Specifies the number of copies to be printed.
DUMMY: Specifies that a dummy data set be allocated.
BLKSIZE(block size): Specifies the block size.
LRECL(record length): Specifies the logical record length.
DSORG(PS|PO|DA): Specifies the data set organization.
RECFM(format[,format...]): Specifies the record format. The values are A, B, D, F, M, S, T, U, and V. You can combine several of these values.
STORCLAS(storage class): Specifies the storage class.
MGMTCLAS(management class): Specifies the management class.
DATACLAS(data class): Specifies the data class.
RECORG(LS): Specifies that a VSAM linear data set be created.
DSNTYPE(LIBRARY|PDS): Specifies the data set type.
SPIN(UNALLOC): Specifies that a sysout data set be spun off at allocation.
NORECALL: Specifies that the allocation request be failed if the data set is migrated.
PATH('pathname'): Specifies that the allocation is for a file in the z/OS® UNIX file system.
PATHOPTS(pathopt[,pathopt]...): Specifies a list of path options: ORDWR OEXCL OSYNC OTRUNC OCREAT OWRONLY ORDONLY OAPPEND ONOCTTY ONONBLOCK.
PATHMODE(pathmode[,pathmode]...): Specifies a list of path modes: SIRUSR SIWUSR SIXUSR SIRWXU SIRGRP SIWGRP SIXGRP SIRWXG SIROTH SIWOTH SIXOTH SIRWXO SISUID SISGID SISVTX
PATHDISP(KEEP|DELETE[,KEEP|DELETE]): Specifies the normal and abnormal file disposition.
FILEDATA(TEXT|BINARY): Specifies whether the data is to be treated as text or binary.

Messages

0-254: Successful completion.
255: The return code is outside the range 0-254 or the tso command ended in error.

Related information

tsocmd