OMVS - Invoke the z/OS shell
Format
OMVS ALARM | NOALARM
AUTOSCROLL | NOAUTOSCROLL
CONVERT(character_conversion_table)
DBCS | NODBCS
DEBUG(NO | YES | EVENT | DATA)
ECHO | NOECHO
ENDPASSTHROUGH(ATTN | CLEAR | CLEARPARTITION |
ENTER | NO | PA1 | PA3 | PF1 | PF2 | PF3 ... PF24 | SEL)
ESCAPE('escape-characters')
LINES(n)
PFn
(ALARM | NOALARM |
AUTOSCROLL | NOAUTOSCROLL |
BACKSCR |
BOTTOM |
CLOSE |
CONTROL |
ECHO | NOECHO |
FWDRETR |
HALFSCR
HELP |
HIDE | NOHIDE |
NEXTSESS |
NO |
OPEN |
PFSHOW | NOPFSHOW |
PREVSESS |
QUIT |
QUITALL |
REFRESH |
RETRIEVE
RETURN |
SCROLL |
SUBCOMMAND |
TOP |
TSO )
PFSHOW | NOPFSHOW
RUNOPTS('LE/370-runtime-options')
SESSIONS(n)
SHAREAS | NOSHAREAS
WRAPDEBUG(n)
Description
Use the OMVS command to invoke the z/OS shell. You can select options on the OMVS command to customize aspects of the shell interface, such as the function keys.
After you are working in a shell session, you can switch to subcommand mode, return temporarily to TSO/E command mode, or end the session by exiting the shell.
Parameters
- ALARM | NOALARM
- Controls the sounding of the 3270 alarm to alert you to particular events.
The default is ALARM.
- ALARM
- Causes the 3270 alarm to sound when the <alert> character is encountered in data being sent to the workstation.
- NOALARM
- Prevents the 3270 alarm from sounding when the <alert> character is encountered in data being sent to the workstation.
- AUTOSCROLL | NOAUTOSCROLL
- Controls the setting of the autoscroll function. The default is AUTOSCROLL.
- AUTOSCROLL
- Specifies automatic scrolling of input and output written to the screen.
- NOAUTOSCROLL
- Specifies that there not be automatic scrolling.
- CONVERT(character_conversion_table)
- Specifies the character conversion table that is used to convert between the z/OS code page and the code page that is used in
the shell.
- data_set_name(member_name)
- Specifies the name of the partitioned data set (PDS) and the name of the member that contains the character conversion table.
- data_set_name
- Specifies the name of the partitioned data set containing the character conversion table to be used.
- (member_name)
- Specifies the name of the character conversion table to be used. It is the name of a member in a
partitioned data set. If both the member_name and data_set_name are omitted, member FSUMQ000 in the default module search order is used as the character conversion table. The following table lists the various formats of the OMVS CONVERT command:
Table 1. Various formats of the OMVS CONVERT command (OMVS command) Command format What it does OMVS CONV((BPXFX111)) See Note 1. OMVS CONV('SYS1.XXXX') Looks for SYS1.XXXX(FSUMQ000). FSUMQ000 is an alias; when shipped by IBM®, it points to BPXFX100, the default null character conversion table.
OMVS CONV('SYS1.XXXX(BPXFX111)') Looks for SYS1.XXXX(BPXFX111) OMVS CONV(XXXX) Looks for prefix.XXXX(FSUMQ000) OMVS CONV(XXXX(BPXFX111)) Looks for prefix.XXXX(BPXFX111) Note:- If the data_set_name is omitted, z/OS
UNIX locates member_name using the default
search order for modules in the system library concatenation. The located
member_name is used as the character conversion table. For example, if you
specify:
the character conversion table is BPXFX111 in the default module search order in the system library concatenation.OMVS CONVERT((BPXFX111))
If the member name is omitted, the OMVS command looks in the specified data_set_name for member FSUMQ000, to use it as the character conversion table. For example, if you specify:
OMVS uses SYS1.XLATE(FSUMQ000) as the character conversion table.OMVS CONVERT('SYS1.XLATE') ...
- If the data_set_name is omitted, z/OS
UNIX locates member_name using the default
search order for modules in the system library concatenation. The located
member_name is used as the character conversion table. For example, if you
specify:
CONVERT((BPXFX450))
. - DBCS | NODBCS
- Specifies whether to use DBCS on 3270-type terminals. The default is DBCS processing.
- DBCS
- Causes OMVS to automatically determine whether the terminal supports DBCS. If so, DBCS
processing takes place. It also enables the OMVS command to handle double-byte data in translated
messages. This operand is ignored if you're not using a DBCS terminal. Double-byte data, including escape character strings, cannot be supplied for any of the OMVS command operands. The following data strings used by OMVS must contain single-byte characters only:
- Escape characters
- Conversion table data set name
- Conversion table member name
- Password or password phrase used to access the conversion table, if one is required
OMVS supports only code pages 939, 1027, and 1047 on DBCS. The null character conversion table (BPXFX100) should be used with DBCS terminals. (It is the default.)
- NODBCS
- Specifies that OMVS operate in SBCS mode only. If you are logged on to a terminal that supports DBCS, this operand allows you to bypass DBCS processing.
- DEBUG(NO | YES | EVENT | DATA)
- Controls the collection and output of debugging information. The default is NO; change the
default setting only if IBM requests it.
- NO
- Indicates that no debugging information is to be written.
- YES
- Indicates that debugging information is collected while the OMVS command runs.
- EVENT
- Causes additional debugging information to be written whenever certain internal events occur in the OMVS command.
- DATA
- Causes any data received from or sent to the workstation to be written. Also, debug information for internal events is recorded.
Also, the ddname for the OMVS debug data set is always SYSFSUMO.
- ECHO | NOECHO
- Enables OMVS to control the visibility of the input area. The
default is NOECHO.
- ECHO
- Allows OMVS to hide or unhide the input area.
- NOECHO
- Prevents OMVS from hiding and unhiding the input area.
- ENDPASSTHROUGH(ATTN | CLEAR | CLEARPARTITION | ENTER | NO | PA1 | PA3 | PF1 | PF2 | PF3 ... PF24 | SEL)
- Specifies a 3270 key that ends TSO/3270 passthrough mode and forces OMVS to return to the shell session. Because this key would be used only during application development, the default is ENDPASSTHROUGH(NO). All 3270 keys can be used by the 3270 application.
- ATTN
- Specifies the 3270 <Attention> key. In some 3270 applications,
this key may be changed to <PA1> before it is seen by the TSO/E
OMVS command. If so, OMVS will never see the <Attention> key;
specify <PA1>instead of <ATTN>.
With some terminal connections, the <ATTN> key may not be available.
- CLEAR
- Specifies the 3270 CLEAR key. In some TS0/3270 applications, the TSO/E OMVS command will not see <CLEAR> when the CLEAR key is pressed. In these cases, specifying ENDPASSTHROUGH(CLEAR) will have no effect.
- CLEARPARTITION
- Specifies the 3270 <Clear Partition> key. This key is effective only if the application is using explicit 3270 partitions.
- ENTER
- Specifies the 3270 ENTER key. This key is useful only if the 3270 application is completely driven by PF or PA keys.
- NO
- No breakout key; this is the default.
- PA1
- Specifies the 3270 <PA1>key. For some TSO/3270 applications, <PA1>
is changed to <ATTN> before OMVS sees it. In these cases, you
should specify ENDPASSTHROUGH(ATTN).
In general, the provider of the TSO/3270 application needs to tell the user whether <PA1>, <ATTN>, or <CLEAR> can be used for ENDPASSTHROUGH.
- PA3
- Specifies the 3270 <PA3> key. The <PA3> key may not be available on some keyboards.
- PFn
- Specifies the 3270 function keys 1-9.
- PFnn
- Specifies the 3270 function keys 10-24.
- SEL
- Specifies the 3270 Cursor Select key. This key is useful only when the 3270 application creates fields on the 3270 screen that can be selected by a light pen.
- ESCAPE('escape-characters')
- Specifies an
escape character as the first character in a two-character sequence that is the EBCDIC equivalent of
an ASCII control character (for example, the EBCDIC
"d"
is the equivalent of the ASCII Ctrl-D). When an escape character is typed in the input area, the next character typed is converted into a special character before it is passed to the shell.You can enter a string up to eight escape characters, enclosed in single quotes with no space between them. (Do not use nonprintable EBCDIC characters.)
The default escape character depends on the character conversion table that is being used. To enter Ctrl-D, for example, type
d
orD
in the input area.If the last character in the input area is one of the escape characters, the <newline> character normally appended to the input data is suppressed. For example, to enter only a <Ctrl-Q> with no final <newline>, type the string
Q
in the input area, and press <Enter>. - LINES(n)
- Controls the amount of output data the OMVS command keeps for scrolling. The default is roughly four screens. You can specify that between 25 and 3000 lines should be kept in the output buffer.
- PFn(ALARM | NOALARM | AUTOSCROLL | NOAUTOSCROLL | BACKSCR | BOTTOM | CLOSE | CONTROL | ECHO | NOECHO FWDRETR | HALFSCR | HELP | HIDE | NOHIDE NEXTSESS | NO | OPEN | PFSHOW | NOPFSHOW | PREVSESS | QUIT | QUITALL | REFRESH | RETRIEVE | RETURN | SCROLL | SUBCOMMAND | TOP | TSO)
- Customizes the settings for the function keys that you use while working in the z/OS shell or in subcommand mode. in
<PFn> The n is a one- or two-digit function key
number from 1 to 24. Do not use a leading zero for a one-digit number. More than one function key
can be assigned the same function. For example, both <PF1> and <PF13> are assigned the
Help function by default. All PF keys can be abbreviated using the usual TSO/E rules. For example,
- OPEN can be abbreviated as O, OP, or OPE.
- NEXTSESS can be abbreviated as NE, NEX, NEXT, NEXTS, NEXTSE, or NEXTSES.
- PFSHOW can be abbreviated as PF, and NOPFSHOW can be abbreviated as NOPF.
- ALARM | NOALARM
- A toggle key used to turn on and off the 3270 alarm that sounds when an
<alert> character is written to the output area (also available in subcommand mode).
The label for this PF key (in the PF key lines at the bottom of the screen) shows up as either ALARM or NOALARM, depending on the current toggle setting. If it is ALARM, pressing this PF key turns the alarm on. If it is NOALARM, pressing this PF key turns the alarm off.
- AUTOSCROLL | NOAUTOSCROLL
- A toggle key used to turn the autoscroll function on and off (also
available in subcommand mode).
The screen automatically scrolls forward when new input is written to the screen.
The label for this PF key (in the PF key lines at the bottom of the screen) shows up as either AUTOSCROLL or NOAUTOSCROLL, depending on the current toggle setting. If it is AUTOSCROLL, pressing this PF key turns the autoscroll function on. If it is NOAUTOSCROLL, pressing this PF key turns the autoscroll function off.
- BACKSCR
- Scrolls the screen backward one full screen, redisplaying previously
displayed output lines. The scrolling ends when the oldest available saved line is reached. (This
option is also available in subcommand mode.)
If you first move the cursor into the output area, the line with the cursor becomes the top line.
- BOTTOM
- Scrolls help information forward to the last panel of information, and scrolls output forward the last full screen (also available in subcommand mode).
- CLOSE
- Ends the displayed session and switches to another one, or returns to TSO/E if the only session was closed (also available in subcommand mode).
- CONTROL
- Treats all characters in the input area as if they were preceded by an escape character. Also, no trailing <newline> is appended to the data.
- ECHO | NOECHO
- A toggle key used to control whether the shell command can hide or
unhide the OMVS command input area.
The label for this PF key (in the PF key lines at the bottom of the screen) shows up as either ECHO or NOECHO, depending on the current toggle setting. If it is ECHO, pressing this PF key allows the current shell command to hide or unhide the OMVS command input area. If it is NOECHO, pressing this PF key prevents the current shell command from hiding or unhiding the OMVS input area.
- FWDRETR
- Retrieves the oldest available input line from a stack of saved input lines, starting with the oldest and moving up to the most recent line (also available in subcommand mode).
- HALFSCR
- Scrolls half the displayed screen forward, allowing room for more output data. If the output area on the screen is not full, half the displayed lines are scrolled off the screen. If you first move the cursor into the output area, the line with the cursor becomes the middle line. (This option is also available in subcommand mode.)
- HELP
- Temporarily suspends the session and displays the help information for the OMVS command. The scrolling function keys can be used to look at the help information. To exit the help information, press the Return function key. (This option is also available in subcommand mode.)
- HIDE | NOHIDE
- Temporarily hides or unhides the input data you type on the shell
command line. If you press this PF key while the input area is hidden, the input area is made
visible. If it is not hidden, the input area is hidden. The input area stays hidden or unhidden until:
- You press <Enter>.
- You press the HIDE | NOHIDE PF key.
- You switch to another session, escape to TSO/E and return, or enter subcommand mode and return.
- NEXTSESS
- Switches to the next (higher-numbered) session (also available in subcommand mode).
- NO
- Deactivates a function key so that it doesn't do anything (also available in subcommand mode).
- OPEN
- Starts a new shell session and switches to it (also available in subcommand mode).
- PFSHOW | NOPFSHOW
- Toggles on and off the display of the active function key settings at the bottom of the screen (also available in subcommand mode, and can be used as PF and NOPF).
- PREVSESS
- Switches to the previous (lower-numbered) session (also available in subcommand mode).
- QUIT
- Ends the displayed session and switches to another one, or returns to TSO/E if the only session was closed (also available in subcommand mode).
- QUITALL
- Ends all shell sessions and causes OMVS to end and to return to TSO/E (also available in subcommand mode).
- REFRESH
- Updates
the screen with the latest output data. Use this function key if the display of output is
incomplete, but the session is now displaying
INPUT
status. (This option is also available in subcommand mode.) - RETRIEVE
- Retrieves the most recently entered input line from a stack of saved input lines, starting with the most recent and moving down to the oldest available line (also available in subcommand mode).
- RETURN
- If help information is displayed, returns you to the session you were in. If you are in subcommand mode, returns you to the shell. (This option is also available in subcommand mode.)
- SCROLL
- Scrolls the last line of output data to the top of the screen, making room for more output data. If Help information is displayed, its data is scrolled. If you first move the cursor into the output area, the line with the cursor becomes the top line. (This option is also available in subcommand mode.)
- SUBCOMMAND
- If you press this key when the command line is blank, it leaves the shell session and
enters subcommand mode.
To run a subcommand without switching to subcommand mode, type the subcommand at the command line and then press the function key. You can enter the OMVS subcommands at the command line when you are in subcommand mode.
- TOP
- Scrolls help information backward to the first panel, and scrolls output backward to a screen full of the oldest available output (also available in subcommand mode).
- TSO
- If you press this
key when the command line is blank, it temporarily suspends a shell session or subcommand mode, and
you are in a TSO/E session. You can enter TSO/E commands. Press <PA1> or the <Attention>
key to exit TSO/E command mode and return to the session you were in. (This option is also available
in subcommand mode.)
To run a TSO/E command without suspending the shell session or subcommand mode, type the command at the command line and then press the function key. When the command completes, you can continue working in the shell session or subcommand mode.
Function key defaults:
PF1(HELP)
PF2(SUBCOMMAND)
PF3(RETURN)
PF4(TOP)
PF5(BOTTOM)
PF6(TSO)
PF7(BACKSCR)
PF8(SCROLL)
PF9(NEXTSESS)
PF10(REFRESH)
PF11(FWDRETR)
PF12(RETRIEVE)
PF13(HELP)
PF14(SUBCOMMAND)
PF15(RETURN)
PF16(TOP)
PF17(BOTTOM)
PF18(TSO)
PF19(BACKSCR)
PF20(SCROLL)
PF21(NEXTSESS)
PF22(REFRESH)
PF23(FWDRETR)
PF24(RETRIEVE) - PFSHOW | NOPFSHOW
- Specifies that the PF keys be shown at the bottom of the screen. The
default is PFSHOW.
- PFSHOW
- Specifies that PF keys be shown at the bottom of the screen.
- NOPFSHOW
- Specifies that PF keys not be shown at the bottom of the screen.
- RUNOPTS('run-time-options')
- Specifies a string containing run-time options, which are passed to Language Environment® when the TSO/E OMVS command starts up,
and to the initial login shell program in the _CEE_RUNOPTS environment variable. These options are
the same as those passed to other Language
Environment programs run from the TSO READY prompt.
The options string can be from 1 to 1000 characters in length, and should contain valid run-time options. It should not contain options such as POSIX(OFF), TRAP(OFF), TRAP(ON,NOSPIE), or MSGFILE(), or characters such as slashes, unbalanced parentheses or quotes, or imbedded NULL characters. Specifying such options or using these characters will cause unpredictable problems when the TSO/E OMVS command runs.
If the RUNOPTS operand is omitted, OMVS uses the RUNOPTS string defined in the BPXPRMxx member of SYS1.PARMLIB that is active for the OMVS kernel. If no RUNOPTS string was defined in BPXPRMxx, no default run-time options are used when the TSO/E OMVS command starts up.
- SESSIONS(n)
- Specifies the initial
number of sessions to be started. The default is 1, and the allowed
range is 1 to 100; most users will use two or three sessions. Note: You can specify a number from 1 to 100 without getting a syntax error on the command. Normally, you cannot start more than several sessions before getting an error message. If you try to start too many sessions (the limit depends on the size of your TSO/E address space), your TSO/E user ID runs out of storage and various unpredictable errors may occur. You may have to log off your TSO/E user ID before you can continue.
- SHAREAS | NOSHAREAS
- Specifies whether to run the shell
program in a separate address space. Both OMVS and the shell will
run in the TSO/E address space when OMVS is invoked with the SHAREAS
parameter. OMVS will use SHAREAS as the default if the shell program is not a SETUID or SETGID program and the owning UID or GID is not the same as the current user.
- SHAREAS
- Runs the
shell program in the same TSO/E address space as OMVS. SETUID and SETGID
shell programs cannot be run with the SHAREAS option unless your UID
or GID owns the shell program. Note: If you end OMVS while in SHAREAS mode, the shell process ends immediately. (It may get killed, but it will usually end by itself when the TTY is closed.)
- NOSHAREAS
- Runs the shell program in a separate address space. SETUID and SETGID shell programs usually require this option.
- WRAPDEBUG(n)
- Controls
how many lines of debug data OMVS writes out before wrapping around
to the top of the debug data set. This option is effective only if
the DEBUG(YES) DEBUG(EVENT),
or DEBUG(DATA) options are used.
The WRAPDEBUG(n) value specifies how many lines of debug data OMVS writes out before wrapping around to the top of the debug data set. The default number of lines is 10 000. The value of n must be between 100 and 1 000 000 000. The debug data set must be large enough to hold n 80-byte lines of debug data. If the debug data set is too small, debug recording stops when the data set fills up.
Subcommands
- ALARM
- Turns on the 3270 alarm which sounds when an <alert> character is written to the output area.
- AUTOSCROLL
- Activates automatic forward scrolling of output as new input is written to the screen.
- BACKSCR
- Scrolls the screen backward one full screen, redisplaying previously deleted output lines. The scrolling ends when the oldest available saved line is reached.
- BOTTOM
- If the help information is displayed, it is scrolled forward to the last panel of information. If output is displayed, it is scrolled forward to the last screen of output.
- CLOSE
- Ends the displayed session and switches to another one, or returns to TSO/E if the only session was closed.
- ECHO
- Allows the current shell command to control whether the OMVS input area is visible or hidden. The HIDE subcommand, NOHIDE subcommand, and HIDE | NOHIDE PF keys can temporarily override the input area visibility set by the current shell command.
- HALFSCR
- Scrolls half the displayed screen forward, allowing room for more output data.
- HELP
- Displays help information
for the OMVS command. To view the help information, use the scrolling
function keys. To return from Help to the session, press the Return
function key.
?
is a short form for the Help subcommand. - HIDE
- Temporarily
hides the input data you type on the shell command line. The input
area stays hidden until you do one of the following actions:
- Press <Enter>.
- Press the HIDE | NOHIDE PF key.
- Switch to another session, escape to TSO and return, or enter subcommand mode and return.
- NEXTSESS
- Switches to the next (higher-numbered) session.
- NOALARM
- Prevents the 3270 alarm from sounding when the <alert> character is encountered in data being sent to the workstation.
- NOAUTOSCROLL
- Turns off the automatic scrolling (AUTOSCROLL) function.
- NOECHO
- Causes the OMVS input area to remain visible regardless of the current shell command. You can use the HIDE subcommand and the PF key to temporarily hide the input area.
- NOHIDE
- Temporarily
unhides the input data you type on the shell command line. The input
area remains visible until you do one of the following actions:
- Press <Enter>.
- Press the HIDE | NOHIDE PF key.
- Switch to another session, escape to TSO and return, or enter subcommand mode and return.
- NOPFSHOW
- Turns off the display of the function key settings and escape characters at the bottom of the screen.
- OPEN
- Starts a new shell session and switches to it.
- PFSHOW
- Displays the current function key settings and escape characters on the bottom two lines of the display screen. A maximum of two screen lines is used. If some function key settings do not fit on the two lines, they are not displayed.
- PREVSESS
- Switches to the previous (lower-numbered) session.
- QUIT
- Ends the displayed session and switches to another one, or returns to TSO/E if the only session was closed.
- QUITALL
- Ends all shell sessions and causes OMVS to end and to return to TSO/E.
- RETURN
- Returns from subcommand mode to the shell session. If help information is being displayed, the session returns to subcommand mode and you must enter the RETURN command again to return to the shell.
- SCROLL
- Scrolls forward the data displayed on the screen, approximately one full screen.
- TOP
- Scrolls help information backward to the first panel. Scrolls output backward to a display of the oldest available output.
- TSO
- Invokes TSO/E command mode. In this mode, you can enter TSO/E commands. Press <PA1>or the <Attention> key to return to subcommand mode.
Usage notes
- The OMVS command is a Language Environment application.
OMVS overrides the default MSGFILE ddname (SYSOUT) and uses ddname
SYSFSUMM.
Normally, any Language Environment error messages from the OMVS command are displayed on the TSO/E terminal. If you want to redirect these messages, you need to allocate the SYSFSUMM ddname instead of the SYSOUT ddname, as is usual with Language Environment applications.
- The language of the OMVS command messages is determined by the PROFILE PLANGUAGE setting when OMVS is invoked. Do not change PROFILE PLANGUAGE while OMVS is running
Return codes
0
- Processing successful.
12
- Processing unsuccessful. An error message has been issued.
Examples
These examples explain how to use the multi-session capability of OMVS:
- To start 2 sessions automatically when
starting OMVS, enter:
OMVS SESSIONS(2)
- To assign the NEXTSESS function to a PF key, enter:
OMVS PF1(NEXTSESS)