Tools for z/OS UNIX System Services

These tools build a collection of useful functions and extensions for the current UNIX System Services environment. Support is included for for the OMVS shell in systems running with German or US Host Emulation Code pages. Editing of UNIX files is supported for all emulation code pages supported by iconv (conversion to and from IBM-1047). To get detailed information how to install the package click on Installation.

Updated: 2003-10-09

Robert Hering

E-Mail: Robert.Hering@de.ibm.com

Table of Contents

Introduction Introduction and comments to the tools contained in this package
AOBROWSE OBROWSE USS files available in ASCII converted to a specified code page if conversion is supported by ICONV
AOEDIT OEDIT USS files available in ASCII converted to a specified code page if conversion is supported by ICONV>
GO Get back to the ISPF/TSO session(s) while OMVS shell session(s) are kept active
GOBROWSE OBROWSE USS files converted to the German code page
GOEDIT OEDIT USS files converted to the German code page
OMVS Run OMVS with a specified OMVS conversion table
PSINFO Get information about active processes
REXX Run a REXX command processor to process SYSCALL, Shell, TSO and REXX commands
RXSHELL Run UNIX commands interactively from TSO foreground or in TSO batch jobs
RXSUSH Switch to SU mode if possible and run UNIX commands in TSO foreground and TSO batch jobs
SAOEDIT OEDIT USS files available in ASCII converted to a specified code page if conversion is supported by ICONV in SU mode
SGOEDIT OEDIT USS files converted to the German code page in SU mode
SOEDIT OEDIT USS files in SU mode
SU Run commands in ISPF/TSO foreground or TSO batch in SU mode
SUOEDIT OEDIT USS files converted to the US code page in SU mode
"SU -"Support Support full shell initialization for the Standard and the C Shell environment when switching to another userid using the "su" command
SWSU Switch to SU mode (temporary) or just run one command with superuser authority in a USS shell environment
SXOEDIT OEDIT USS files converted to a specified code page supported by ICONV in SU mode>
UOBROWSE OBROWSE USS files converted to the US code page
UOEDIT OEDIT USS files converted to the US code page
XOBROWSE OBROWSE USS files converted to a specified code page supported by ICONV
XOEDIT OEDIT USS files converted to a specified code page supported by ICONV
HintsTips Additional Hints and Tips how to use these USS tools
Installation Detailed information how to install the package

  Introduction

This package includes several z/OS UNIX tools which are especially useful in the following situations:

  • Editing IBM-1047 UNIX files
  • Working in the OMVS Shell
  • Working with UNIX System Services as a BPX.SUPERUSER


It was made available from the z/OS UNIX tools page in June 2001 for the first time. In the meantime several updates were needed to incorporate changes made within interface routines in z/OS V1.3 (when editing UNIX files). These modifications have been done in this new version. Furthermore, some new functions have been added.

All the BROWSE and EDIT tools in this package which handle code page conversion from and to the standard z/OS UNIX code page are using a temporary file in the /tmp/ directory with all " /"-characters replaced by " \" in order to provide the impression that the user is working with the original file. Please note, that it is necessary to end an edit session in order to activate the modifications in the original file.

In this description the term z/OS is a synonym for both, OS/390 and z/OS. If you see BPX.SUPERUSER this means a superuser or a user with READ access to FACILITY profile BPX.SUPERUSER. SU mode serves as a short form for superuser mode, i.e. running with real and/or effective UNIX UID value set to 0. The term IBM-1047 USS file is a short form for a UNIX file with a contents composed in the standard z/OS UNIX code page IBM-1047, often simply referenced as "C".

Before providing a description of the tools it is the right place to say thank you to all the customers and IBM colleagues which tested specific tools, sent suggestions for changes or enhancements. Especially I want to thank Britta Kuehn for her help in putting together the German conversion table and Hans-Dieter Mertiens for testing it and distributing it to many customer locations and also for his suggestions regarding the "su -" support.


  AOBROWSE
This function allows browsing USS files available in ASCII from the OMVS shell ( aobrowse) or from ISPF/TSO ( tso aobrowse) according to your (country) terminal emulation used. The syntax is the same as with obrowse. If you omit the name of a file the "Browse Entry Panel" will be displayed.

To run AOBROWSE in SU mode have a look to Running BROWSE Commands in SU mode in topic Hints and Tips.


  AOEDIT
This tool allows editing USS files available in ASCII from the OMVS shell ( aoedit) or from ISPF/TSO ( tso aoedit) according to your (country) terminal emulation used. The syntax is the same as with oedit. If you omit the name of a file the "Edit Entry Panel" will be displayed.

You may use SAOEDIT to run AOEDIT in SU mode.


  GO
The idea behind this function had been mentioned by Bill Schoen long ago in a UNIX forum entry. When recognizing that only a few USS users were/are aware of this simple trick to get back to ISPF from the OMVS shell environment I decided to make it a tool and name it GO like "Go to ISPF". Just enter

                                       go
                               

in an OMVS shell to get (back) to your ISPF/TSO environment and all active ISPF sessions while the OMVS shell session(s) are kept. Press PF3 on the ISPF session marked with an application id of OMVS to return to the UNIX shell session(s).


  GOBROWSE
Allows to browse IBM-1047 USS files from the OMVS shell ( gobrowse) or from ISPF/TSO ( tso gobrowse) with the correct character display if you are using a German terminal emulation (IBM-273 or IBM-1141). The syntax is the same as with obrowse. If you omit the name of a file the "Browse Entry Panel" will be displayed.

To run GOBROWSE in SU mode have a look to Running BROWSE Commands in SU mode in topic Hints and Tips.


  GOEDIT
allows to edit IBM-1047 USS files from the OMVS shell ( goedit) or from ISPF/TSO ( tso goedit) with the correct character display on input and output if you are using a German terminal emulation (IBM-273 or IBM-1141). The syntax is the same as with oedit. If you omit the name of a file the "Edit Entry Panel" will be displayed.

You may use SGOEDIT to run GOEDIT in SU mode. To use GOEDIT for editing CRON tables have look to Editing CRONTABs in topic Hints and Tips.


  OMVS
allows to work in the OMVS shell with the standard z/OS USS code page IBM-1047 active while all special characters like " |", " [", " ]", " {", " }" and so on are interpreted and displayed correctly on input and output if you are using a German or the US terminal emulation. You just need to use a special option to reflect the code page that you are using.

Use

                                       tso %omvs g
                               

If you are using IBM-273 or IBM-1141, use

                                       tso %omvs u
                               

if your terminal emulation is IBM-037. To get a more detailed information how to specify parameters just enter

                                       tso %omvs ?
                               

Regarding the German terminal emulation this functionality is based on the conversion table file within UNIX.LINKLIB. If you want to use a USS conversion table by default have a look to Using specific USS conversion tables by default in Hints and Tips. The information given will provide the means how to use the standard OMVS command again instead of the REXX procedure!


  PSINFO
allows to get information about active processes similar to USS shell or ISHELL command ps. The command is supported in ISPF/TSO ( tso psinfo) and the UNIX shell environments ( psinfo). If the user is a BPX.SUPERUSER and the command is run from a USS shell environment it is run in SU mode automatically. To get a detailed help just enter

                                       psinfo
                               

 REXX

is supported in ISPF/TSO ( tso rexx) and USS shell environments ( rexx) and allows to run TSO, SYSCALL, USS Shell and REXX commands interactively. Just have a look to the following samples (which may be run by a BPX.SUPERUSER) and try yourself.

"One-line" command samples in ISPF/TSO:

(*1)  
                                      tso rexx s geteuid
(*2)  
                                      tso rexx s seteuid 0
(*3)  
                                      tso rexx s seteuid xxx
(*4)  
                                      tso rexx s setuid 0
                               

( *1) - Displays the effective UID shown as the "OMVS Return value"
( *2) - Sets the effective UID to 0
( *3) - Resets the effective UID to xxx, if this is the real UID (<> 0) of the BPX.SUPERUSER
( *4) - Will not work as setting the UID value to 0 is not allowed in ISPF/TSO

Using the tool as an "Interactive REXX command processor" in a USS shell environment:

                                       id
rexx
sh "id"
s setuid 0
sh "id"
exit
id
                               

  RXSHELL
RXSHELL may be used to run UNIX commands from TSO foreground (e.g. tso rxshell) or in TSO batch jobs. Following a list of functions and syntax rules how to enter commands or provide input data.

  • In a batch job, environment variables can be set to be used in the commands.
  • Command lines ending with a dash ( - ) may be continued on the next line.
  • Leading blanks of a continuation line are removed.
  • Commands ending with a plus sign ( + ) are not displayed (or repeated) in the output data.
  • Lines starting with a pound sign ( # ) in column 1 are treated as a comment.
  • Allows the user to specify a timeout value to automatically cancel a command if it does not end within the specified amount of time. A value of "0" indicates no timeout setting is used. If "R0" is specified output messages are displayed continuously. Otherwise they appear when the command has ended.
  • Allows a "one-line" command call if a UNIX command is provided as a parameter with the command.
  • The commands are run in a z/OS UNIX shell environment as follows with no expensive shell initialization (just using "sh -c", not "sh -Lc").
  • At the top of the job output data you find information and a command how to stop the processing of the job as smoothly as possible, if you should need to do that for some reason.


Following some sample commands entered from TSO:

                                       tso rxshell
 Enter command input data or "exit" to exit processing:
pwd
 pwd
 /u/hering
id -u+
 888
 Enter command input data or "exit" to exit processing:
exit
                               

A sample JCL is provided in the USSTools Library and in Running USS commands from TSO Batch in Hints and Tips.


  RXSUSH
RXSUSH may be used to run UNIX commands from TSO foreground (e.g. tso rxsush) or in TSO batch jobs. In addition to the rules for RXSHELL the following is done.

  • Exploit access to BPX.SUPERUSER when needed by:
    • Switching UID settings to “ 0” as best as possible according to the environment.
    • Switching back UID settings to the original value in TSO foreground.
  • Using the root directory ( “ /” ) as the home and working directory


Following some “one-line” commands from TSO:

                                       tso rxsush id
 UID setting switched to 0...
 id -u
 0
tso rxsush pwd
 UID setting switched to 0...
 pwd
 /
                               

You can create JCL the same way as for RXSHELL. See Running USS commands from TSO Batch in Hints and Tips.


  SAOEDIT
A BPX.SUPERUSER may use this command to run AOEDIT in SU mode. It is supported from ISPF/TSO ( tso saoedit) and the OMVS shell environment ( saoedit).


  SGOEDIT
A BPX.SUPERUSER may use this command to run GOEDIT in SU mode. It is supported from ISPF/TSO ( tso sgoedit) and the OMVS shell environment ( sgoedit).


  SOEDIT
A BPX.SUPERUSER may use this command to run OEDIT in SU mode. It is supported from ISPF/TSO ( tso soedit) and the OMVS shell environment ( soedit).


  SU
A BPX.SUPERUSER may use this command to run commands in SU mode from ISPF/TSO. Have a look to the following samples:

                                       su oput usstools(etcsetup) '/etc/.setup'
su rexx s chmod /etc/.setup 755
                               

  SUOEDIT
A BPX.SUPERUSER may use this command to run UOEDIT in SU mode. It is supported from ISPF/TSO ( tso suoedit) and the OMVS shell environment ( suoedit).


  "su -" Support
If correctly installed this function supports a complete shell environment initialization if you switch to another userid running in the Standard or the C Shell environment. This additional parameter seems to be available on many other UNIX platforms but is not in z/OS USS by default yet. Instead of entering just the other userid you will have to precede it with " -":

                                       su - newuser
su - -s newuser
                               

To use this support some additional customization steps are needed. Have a look to Customizing the "su -" Support in topic Installation.


  SWSU
A BPX.SUPERUSER may use this tool to work as a superuser in USS shell environments similar to the su shell command. Unlike the standard command it allows to append a UNIX shell command which will be run in SU mode. And this is very useful in batch mode, e.g. when using BPXBATCH. See the following examples:

                                       swsu chmod 755 /etc/.setup
swsu ps -e | grep cron
                               

  SXOEDIT
A BPX.SUPERUSER may use this command to run XOEDIT in SU mode. It is supported from ISPF/TSO ( tso sxoedit) and the OMVS shell environment ( sxoedit).


  UOBROWSE
This allows browsing IBM-1047 USS files from the OMVS shell ( uobrowse) or from ISPF/TSO ( tso uobrowse) with the correct character display if you are using the US terminal emulation (IBM-037). The syntax is the same as with obrowse. If you omit the name of a file the "Browse Entry Panel" will be displayed.

To run UOBROWSE in SU mode have a look to Running BROWSE Commands in SU mode in topic Hints and Tips.


  UOEDIT
This allows editing IBM-1047 USS files from the OMVS shell ( uoedit) or from ISPF/TSO ( tso uoedit) with the correct character display on input and output if you are using the US terminal emulation (IBM-037). The syntax is the same as with oedit. If you omit the name of a file the "Edit Entry Panel" will be displayed.

You may use SUOEDIT to run UOEDIT in SU mode. To use UOEDIT for editing CRON tables have look to Editing CRONTABs in topic Hints and Tips.


  XOBROWSE
This allows browsing IBM-1047 USS files from the OMVS shell ( xobrowse) or from ISPF/TSO ( tso xobrowse) with your local emulation code page. The syntax is the same as with obrowse. If you omit the name of a file the "Browse Entry Panel" will be displayed.

To run XOBROWSE in SU mode have a look to Running BROWSE Commands in SU mode in topic Hints and Tips.


  XOEDIT
This allows editing IBM-1047 USS files from the OMVS shell ( xoedit) or from ISPF/TSO ( tso xoedit) with your local emulation codepage. The syntax is the same as with oedit. If you omit the name of a file the "Edit Entry Panel" will be displayed.

You may use SXOEDIT to run XOEDIT in SU mode. To use XOEDIT for editing CRON tables have look to Editing CRONTABs in topic Hints and Tips.


  Hints and Tips

  Using specific USS conversion tables by default
If you want to use the German conversion table by default you can put library UNIX.LINKLIB in front of SYS1.LINKLIB within the LINKLST chain or even simpler and more flexible put the following two MVS system commands into a COMNDxx parmlib member or run them automatically using another means:

                                       SETPROGLPA,ADD,MODNAME=(FSUMQ000),DSNAME=
 UNIX.LINKLIBSETPROGLPA,ADD,MODNAME=(BPXFX000),DSNAME=UNIX.LINKLIB
                               

This will provide the following advantages:

  • It is no longer necessary to use the REXX procedure OMVS if you want to use the German conversion table support and the standard OMVS command can be used instead again. The REXX is only needed if you want to run the OMVS shell together with the US terminal emulation or if you want to avoid any conversion by using the "NULL" conversion table.
  • When using OCOPY, OPUT(X) or OGET(X) you can use the parameter  CONVERT( YES) to achieve a data conversion between the German and the standard UNIX code page.

You can make use of this "default" support for the US terminal emulation as well as you have the REXX procedure available for all the other situations again. BPXFX000 is defined as an alias of BPXFX111 (the US code page conversion table) in SYS1.LINKLIB already. The only thing needed is to define FSUMQ000 as an alias of BPXFX111, too. By default FSUMQ000 points to the null character conversion table BPXFX100.

  Running USS commands from TSO Batch
Following you find a sample how to run USS commands in a TSO batch job and easily get the UNIX output data to your job SYSOUT. It is provided within the package library, named USSBATCH.

                                                                                //UNIXJOBJOB,'USSCommands',NOTIFY=&SYSUID.,REGION=0M
//* ----------------------------------------
//* Run USS shell commands in TSO batch mode
//* Property of IBM  (C) Copyright IBM Corp. 2002-2003
//* ----------------------------------------
//SET TIMEOUT=R0  <=== Timeout value in seconds, <R>0=no timeout
//SET RXSHCMD=RXSHELL  <=== RXSHELL or RXSUSH
//SET REXXLIB=UNIX.REXX.EXEC  <===  
 
SYSEXEC library
//*----------------------------------------
//OMVSEXECPGM=IKJEFT01,PARM= 
'&RXSHCMD.&TIMEOUT.'
//SYSEXECDDDSNAME=&REXXLIB.,DISP=SHR
//STDENV   DD DATA,DLM=##
# -----------------------------------------
   TSOALLOC=sysexec
    sysexec='UNIX.REXX.EXEC'
       PATH=/u/bin:/bin
    tmpfile=/tmp/my.testfile
# -----------------------------------------
##
//STDIN    DD DATA,DLM=
 

 

## 
# ----------------------------------------- 
id swsu id
chmod chmod 2> /dev/fd1 ! iconv -f IBM-1047 -t IBM-273 touch
  $tmpfile && chmod 644 $tmpfile && ls
-E $tmpfile
-
&&  rm $tmpfile
&& ls -E$tmpfile;+
#------------------------------------------
##//SYSTSINDDDUMMY//SYSTSPRTDDSYSOUT=*,LRECL=136,RECFM=V
//* ----------------------------------------                                      
                               

  Editing CRONTABs
To be able to use all special characters as with goedit (or uoedit as well) when editing a CRONTAB file you may do one of the following.

  1. Enter

    EDITOR=goedit crontab -e
  2. Or run

    export EDITOR=goedit

    followed by

     crontab -e
     

  Running BROWSE Commands in SU Mode
Running browse commands in SU mode is supported by using the SU command. See the following sample.

                                       tso su gobrowse /etc/rc
                               

  Installation

Preparation
You need to run on OS/390 V2.7 (SYSMVS Level SP6.0.7) at least to be able to install the package as suggested in the following. Get the file USSTOOLS.UNLOAD.BIN and put it binary to an FB80 data set in your z/OS system. See the following FTP example:

                                       ftp my.zos.system
myuser
mypasswd
binary
quote site blk=3120 lrecl=80 recfm=fb
put usstools.unload.bin usstools.unload
                               

Afterwards run the following command on your z/OS system:

                                       >receive indsn(usstools.unload)
                               

Installing the Tools
Now you should be able to edit or view the PDS data set USSTOOLS. The first member is named $INSTALL. Near the top you will find a sequence of job variables that may be customized according to your installation's naming conventions and file structure. A copy of this HTML file (ready for binary transfer to a workstation) should be available with the name specified for variable HTMLFILE after running the install job. What need to exist are a REXX library like UNIX.REXX.EXEC which should be located within the SYSPROC or SYSEXEC library chain and a UNIX path like /u/bin which is addressable through the PATH environment variable.

If you change the name of the UNIX.LINKLIB you need to correct the conv_parm or conv_ger statement value "'UNIX.LINKLIB(BPXFX273)'" in the following REXX procedures accordingly:

  • GOEDIT
  • OMVS

Furthermore, you should edit and adopt the following settings in REXX procedure GOEDIT

                                       backslash = "?" /* Back slash */
.
xoedit_ux_codepg = "IBM-1047" /* Use iconv for */
xoedit_ed_codepg = "IBM-273" /* IBM-273 <-> IBM-1047 */
aoedit_ux_codepg = "ISO8859-1" /* Use iconv for ISO */
aoedit_ed_codepg = "IBM-273" /* ASCII <-> IBM-273 */
                               

Replace the " ?" by the character that represents the back slash in your local code page used and also change “ IBM-273” accordingly. You may also change settings later on when the files are copied to into the target REXX Library. But then you need to modify all the following files, depending on what is needed when they are used: GOBROWSE, GOEDIT, OMVS, XOBROWSE, XOEDIT, UOBROWSE, UOEDIT, AOBROWSE, AOEDIT. If you use the US and a local terminal emulation in parallel it may be useful to replace the back slash character in UOBROWSE and UOEDIT after installation, of course. Finally a last example; if you decide to use XOBROWSE and XOEDIT with the US emulation replace IBM-273 by IBM-037.

  Customizing the "su -" Support

To use the functionality of the "su -" support there are some more customization steps which need to be performed.

  • In order to be able to use it with the C Shell environment the file /etc/csh.cshrc.append needs to be appended to /etc/csh.cshrc.
  • The following statement must be included in /etc/profile
                                               export ENV=/etc/.setup
                                       
    
  • If a user has already an own SETUP file active the contents of /etc/.setup should be included into the user's .profile in his HOME directory.

Please note, that this /etc/.setup file also controls the prompt setting displayed in a USS shell environment. If you do not like it remove the lines dealing with the prompt setting.

Assemble and Link-edit the German Conversion Table File

If you should ever need to assemble and link-edit the German conversion table file BPXFX273 again use the following LINK parameters and INCLUDE statements:

                                       ...//PARM='LIST,REUS,RENT,NCAL,LET,MAP,AMODE=31,RMODE=ANY,AC=0'
...
//SYSLIN   DD DATA,DLM=##
 INCLUDE BPXFX273
 ENTRY BPXFX273
 ALIAS BPXFX000
 ALIAS FSUMQ000
 NAME BPXFX273(R)
##
                               

 

Contact IBM

Browse z/OS