RUNC

Easy Commands for the ISPF Edit User

By Lionel B. Dyck

Table of Contents

Change History

Introduction

What is RUNC?

What benefit does RUNC provide?

RUNC

RUNC Command Syntax

RUNC Command Options

RUNC Defaults

Format for Commands

Command Types and Syntax

Documentation

Using the <START> and <END> statements

Using the <EXIT rc> statement

Workflows

Symbolics

Selecting Records to Execute under RUNC

Using the RUNC command

ERC

ERC Command Syntax

Samples

TSO

z/OS

EDIT

JES2

JES3

OMVS

Documentation

Change History

Starting with Version 3.2:

Version

Date

Description

4.6

12/21/2018

Add new SET command to define a symbolic

4.4

12/17/2018

Add SLEEP command

4.3

12/03/2018

Add RENAME command

4.2

05/02/2017

Added more information on using RUNC in a workflow

4.2

04/18/2017

Added:

- EJES ST and EJES ST xxx

- SDSF ST and SDSF ST xxx

4.1

03/27/2017

Add:

-I option to display each command results individually if a range or –ALL is requested

<EXIT rc> to test the return code from the current command and cease processing if the return code is equal or greater.

Add <Start> and <End> statements to define a range for processing.

4..0

03/21/2017

Added documentation that will appear in a popup.Using tags <DOC>, <TITLE>, and </DOC>

Support Macro and Parm on both Edit and View, Including Edit Member

3.9

02/22/2017

Add new option –BS to toggle the bypass prompting for RUNC supported symbolics

3.8

02/21/2017

Add doc on use of MEMBER(x) option with Browse, Edit and View

3.7

02/17/2017

Add information on Browse, Edit and View use of VOLUME keyword

3.6

01/31/2017

Bug fixes to the code

3.4

01/26/2017

Add

–L option to log messages to a dataset based on installation default

-LD to log to a sequential dataset

-LP to log to a pds member

-LX to override any log option defaulted to in the –O settings

-C to display all log datasets

%RUNCLOG used by –C option

3.3

01/10/2017

Add new –D(prefix) option

Add &DATE symbolic (same as &UDATE – mm/dd/yy)

Change symbolic JULIAN to JDATE to conform to other date symbolics

3.2

01/03/2017

Added &RDSN, &RMBR and &RMEM pre-defined symbolics

Introduction

What is RUNC?

RUNC is short for Run Command. It is an ISPF Edit command that will execute many different types of commands that are stored within a dataset, or member. The dataset or member must be opened using ISPF Edit (or View). RUNC supports almost two dozen pre-defined symbolics as well as user defined symbolics to enable the commands to be generalized. Using some of the special RUNC specific control statements a workflow can be constructed.

ERC, or Execute Run Command, is an ISPF command that can be used to access the dataset, or member, where the commands are stored. This is provided to simplify access without requiring the user to navigate multiple ISPF panels to get to the command dataset.

What benefit does RUNC provide?

The benefit is that the dataset, or member, containing the commands can include comments to document the commands in the dataset, or member. The dataset, or member, could also be JCL or a document in which commands are included as comments.

For example, a document on how to allocate a partitioned dataset to contain JCL, could have an explanation of what a partitioned dataset is, how to calculate the size, and how to calculate the number of directory blocks, or whether to use a PDSE instead. Along with the text the TSO commands could be included in the dataset, or member, to perform the allocation. There could be a sample command for a simple PDS and one for a PDSE. The user can then use RUNC to execute the allocation command for the PDS or PDSE that they are interested in without having to copy and paste the command, or having to retype it.

For systems programmers and operators, a PDS could be created with members for different functions. For example, a member called ZOS could be created with many frequently, and infrequently, used z/OS commands. Using this member the systems programmer, or operator, would be able to find the command they need to use and easily execute it. The members could be more granular with one for GRS, one for SMF, one for JES2, or JES3, etc. Then using the ERC command (see below) the user would have quick access to the desired member.

A workflow can be created to provide a tested, reliable, repeatable, process such as for use during a disaster recovery to reconfigure the environment at the DR site, by novice system programmers, for processes that are performed infrequently, and to eliminate the need to write an ISPF dialog to do a repeatable process.

RUNC

This section will discuss how to use the RUNC command and how to code the commands in the dataset or member.

RUNC consists of an ISPF Edit command that processes records selected using C or S for an individual record or pairs of CC or SS for consecutive records. Excluded records are always ignored. A filtering option with RUNC, using the ONLY keyword, can also be used alone, or in conjunction with excluded records.

RUNC Command Syntax

RUNC is an ISPF Edit command that is used on the ISPF Edit command line. There are several options that can be specified on the command and all of them are optional.

RUNC Command Options

Option

Description

Blank

Default processing

? or HELP

Display the ISPF Tutorial for RUNC

N

The number of leading characters to skip over to find the command. Useful to skip over comments in the record.  The default is 0.

-A or –ALL

Process ALL commands found in the data.

-B

ISPF Browse the messages generated by the executed commands

-BS

Toggle bypassing the prompt for RUNC supported symbolics

-C

Display a list of all LOG datasets created by RUNC

-D

–D(prefix)

Insert the messages generated by the executed commands in the edit data after the command as permanent records.

If a prefix is specified then it will have leading and trailing blanks removed and will be inserted before the messages with an intervening space. (e.g. –D(>)

-I

Display the command messages for each command as they are processed.

-L

Log all messages to a dataset.

The installation defines whether the dataset is a sequential dataset which results in one per RUNC use, or a PDS where there is one PDS per day with a member for each RUNC use.

The dataset name is hlq.RUNC.Dyymmdd.Thhmmss.LOG for sequential or hlq.RUNC.Dyymmdd.LOG for a PDS.

See –LD and –LP for more information

-LD

Log to a sequential dataset

One per RUNC usage

-LP

Log to a PDS member

One PDS per day and one member per RUNC usage

-LX

Turns off logging if logging was enabled by default (use of –O) for the user

-N

Insert the messages generated by the executed commands in the edit data after the command as notelines.

-O

Display panel to review or update user RUNC defaults

-R

Toggles the installation default. If the default is to Always generate a report even if the command does not generate messages then the toggle will turn that off, and vice versa. Some commands, notably ISPF and some OMVS, do not generate any messages.

-S nnn

Stop execution if the return code is greater than nnn. This only applies when executing multiple commands in one RUNC invocation.

-T

Do not capture any of the generated messages so that the messages generated by the commands display on the terminal.

-V

ISPF View the generated messages from the executed commands. This is the default.

-W nnn

-W W

Works with –D and –N to wrap messages longer than nnn when inserting them into the data.

When W is used then the wrap value is set to the actual Edit Data Width.

The wrap will occur at the nearest blank or at the exact character location depending on the data.

ONLY(xxx)

Limits the commands to be selected to only those with xxx in the command.

PREFIX(xxx)

Prefix all TSO commands with xxx. This only works for TSO commands.

SUFFIX(xxx)

Suffix all TSO commands with xxx. This only works for TSO commands.

RUNC ignores all records that are hidden using the ISPF exclude (X) process. When used with –A, or –ALL, this can be an easy way to bypass unwanted commands without having to select each individual command or command ranges.

Notes

1. –T will override –D, -I, -L, -N, and -R

2. –D and –N will override –B,-I, -L, -T, and –V

3. –L logging dataset type is defined in the RUNC exec at installation time.

RUNC Defaults

The first time that RUNC is used an ISPF Panel will be presented to the user to set the RUNC defaults that will be used. This Panel can also be requested using the –O option when using RUNC.

----------------------- RUNC User Review/Update Defaults ----------------------

Command ===>

N (Y/N)    -B Browse the generated report of all messages

N (Y/N)    -T No report - all messages to the terminal

Y (Y/N)    -V View the generated report of all messages

N (D/P/N)  -L Log all messages to a permanent dataset

N (Y/N)    -D No report - all messages inserted as Data records

Data Prefix:

N (Y/N)    -N No report - all messages inserted as Notelines

Y (Y/N)    -R Generate a report of all messages

N (Y/N)    -BS Bypass prompt for supported symbolics

N (Y/N)    -I Display Individual Command messages

0 (###)    -S Stop multiple command processing if return code exceeds nnn

0 (###)    -W Wrap -D and -N messages to nnn characters (W = Data Width)

(Y/N)     Save as permanent defaults

Notes:      1. -D and -N override -B -I -T -V and -L

2. -T override -D -I -N -R and –L

Press PF3 to continue

This figure also shows the default options used by RUNC which are to View any messages generated by the selected command(s) and to not generate a report if the selected commands do not generate any messages.

The use of –R is useful to generate a report that can be retained, using ISPF Create or Copy, for audit or reference purposes. Note that some commands do not generate any messages, for example ISPF dialogs, so the only message in the report would be the command start and command return code.

Format for Commands

All commands are entered in one, or more, records. Using the following syntax:

Comments start in column 1. Supported comment formats are:

*

/*

//*

//

Use RUNC #, where # is the number of characters to skip over to bypass the comment, to execute commands that are within comments.

The command data can be numbered or un-numbered as the sequence numbers will be ignored.

Command Types and Syntax

Below is a table documenting the supported command types and their supported syntax. The command type can be upper, lower, or mixed case.

Command Type

Syntax

BROWSE

Browse a dataset:

BROWSE Ddataset(dsname)

BROWSE Dataset(dsname) Volume(volser)

BROWSE Member(member-name)

EDIT

Any ISPF Edit command

edit x all

edit x all;find &string all

Note: The command will also affect the record with the command

Or to edit a dataset:

EDIT DATASET(xxx)

EDIT DATASET(xxx) VOLUME(volser)

EDIT Member(xxx)

EDIT Member(xxx) MACRO(macro)

EDIT Member(xxx) MACRO(macro) PARM(parm)

EDIT Dataset(xxx(member))

EDIT Dataset(xxx(member)) MACRO(macro)

EDIT Dataset(xxx(member)) MACRO(macro) PARM(parm)

EJES

(E)JES JES2/JES3-or-z/OS-command

ejes d ts,l

ejes d smf

ejes d smf;d asm

ejes st

ejes st xxx

ISPF

SELECT . . .

select panel(isp@mstr)

select cmd(%xyz option1 option2)

select pgm(iefbr14) parm(abc)

ISPExec . . .

Ispexec libdef . . .

OMVS

OMVS command

omvs ls –la

omvs pwd;id

omvs su;cat /etc/rc

RENAME

RENAME dataset volser from-member-name to-member-name

rename sys1.parmlib sys1p0 iggcat00 iggcat09

rename sys1.parmlib * iggcat00 iggcat09

SDSF

SDSF JES2/JES3-or-z/OS-command

sdsf d ts,l

sdsf d smf

sdsf d smf,d;asm

sdsf st

sdsf st xxx

SET

Define a user symbolic to be used within the RUNC script:

set symbolic = value

The value is case insensitive and does not require quotes unless the usage requires it. These symbolics will not generate a popup prompt.

SLEEP

Sleep for ‘nn’ seconds

sleep 1

Default is 5 seconds.

TSO

Just enter the command on the record

lista sta

st

alloc ds(test.pds) new spa(15,15) tr recfm(f b) +

lrecl(80) blksize(0)

free . . .

altlib . . .

TSO Console

CONS console-command

cons d ts,l

cons d smf

cons d asm

VIEW

View a dataset:

VIEW DATASET(xxx)

VIEW DATASET(xxx) VOLUME(volser)

VIEW Member(xxx)

VIEW MEMBER(xxx) MACRO(macro)

VIEW MEMBER(xxx) MACRO(macro) PARM(parm)

VIEW Dataset(xxx(member))

VIEW Dataset(xxx(member)) MACRO(macro)

VIEW Dataset(xxx(member)) MACRO(macro) PARM(parm)

Documentation Popup

<DOC>  must be on a record by itself to begin the documentation section

</DOC> must be on a record by itself to end the documentation section

<TITLE> followed by up to 32 characters and on a record between the <DOC> and </DOC> records will be used for the popup title.

Documentation records must be between the <DOC> and </DOC> records and may be up to 72 characters in length.

Exit Return Code Check

<EXIT rc> must be on a record by itself and the rc will be compared to the last executed command return code is equal to or greater than the rc in the exit test then RUNC processing will cease.

Start and End Range

<START> must be on a record by itself to begin the start of the range.

<END> must be on a record by itself to end the range.

Any valid RUNC command may be between these two statements.

The Edit, (E)JES, SDSF, and OMVS commands allow multiple commands on the same record separated by a semi-colon ‘;’.

The use of the Member option with Browse, Edit, and View, will perform that action on the requested member in the active dataset. The active dataset volser will be automatically added to the action.

Commands can continue to the next record by ending the record with a ‘+’:

omvs su;  +

ls –la; +

pwd

The use of all commands is dependent upon the level of security authorization that the user has. (E)JES, SDSF, OMVS, and TSO Console commands may be restricted using the sites security package. Some TSO commands may also be restricted. The key is, if the user can use the command outside of RUNC then they can use it with RUNC.

Comments may be included on the record with the command. Comments must start with a /* and there is no requirement for a closing */.

Comment example:

LISTD &dataset /* this command will invoke the TSO LISTD and prompt for a dataset

Symbolics, discussed below, are supported on all commands and in the documentation popup statements.

Documentation

The documentation popup is a tool that can be used with RUNC –ALL to help guide the user through a series of commands or processes.

A sample member with documentation:

cons d iplinfo

<doc>

<title>    Sample Title for Documentation

test record 1

test record 2

test record 3

</doc>cons d smf

In the example above are two console commands with a sample documentation popup text in between.

The sample documentation popup will look like this:

Use of PF3 closes the popup and RUNC processing continues to the next command.

To cancel further RUNC processing, enter CANCEL in the ISPF command field.

This can be very useful in a DR situation where the individual performing the DR may not be that experienced but they can follow instructions. Documentation popups can be used liberally with the required commands such as EDIT, CONS, EJES/SDSF, etc. to guide the individual in performing the DR tasks.

Symbolics may be used in both the title and documentation records. Be aware that a symbolic may extend the title (32 characters) or text (72 characters) beyond the supported limits.

Using the <START> and <END> statements

Define a range of statements to be processed by using the <START> statement followed by any valid RUNC supported command and ending with the <END> statement.

Note that the <START> record must be selected using any of the prior sections methods.

Using the <EXIT rc> statement

This statement is used to force RUNC to exit if the prior return code is equal to, or higher, than the rc in the statement.

Workflows

A workflow is a defined, repeatable, process. Workflows are typically created as a way to avoid having to perform a process manually or having to write specialized code (CLIST, REXX, ISPF) for important processes. Some instances where workflows are helpful are:

a) Novices who need to perform a process but haven’t learned yet. Provide them with a workflow to perform the process and they can learn by reviewing the workflow while getting the job done.

b) Repeatable processes that occur infrequently. By documenting the process in a workflow there is less chance of the process failing.

c) Disaster Recovery (DR) is a repeatable process that occurs infrequently that must be performed error free and in a timely manner. A workflow can help to automate the recovery process to allow the return to service to occur sooner.

Use of the <DOC><TITLE></DOC> to provide popup guidance to the user, combined with the <START> and <END> to define the range of statements to process is what defines a workflow. Adding in the <EXIT rc> statements to terminate the processing if an unexpected return code occurs will help insure the integrity of the process.

If an exit occurs prior to the end of the workflow then the workflow can be easily restarted by using the standard RUNC record selection commands, or editing the workflow to insert a new <START>.

Use of the EDIT command with Macro and Parm can simplify the workflow:

View Member(step2) Macro(runc) parm(-a)

<Exitrc 4>

This will open member step2 within the current dataset and execute the RUNC command with a parm of –A to process all records. The <Exitrc 4> will cause the workflow to terminate if the processing in member step2 has a return code equal or greater than 4.

Symbolics

All commands can include one, or more, symbolics. A symbolic is a 1 to 8 character word beginning with an &. If a double & is found, e.g. &&, then the first will be retained as part of the command text.

When a symbolic is found it will cause RUNC to present to the user an ISPF Panel with the symbolic and a field to enter the value to be used for that symbolic. If a symbolic is used more than once the user is only prompted once.

RUNC supports a number of pre-defined symbolics that will be pre-filled in for the user:

Symbolic

Description

&DATE

Date mm/dd/yy

&DD

2 digit Day of Month

&DOY

Day of year (e.g. 001)

&EDATE

European Date (dd/mm/yy)

&HHMM

Hours and Minutes

&JDATE

Julian Date (e.g. 16001)

&LPAR

Active LPAR Name

&MM

2 digit Month

&MONTH

Month (e.g. January)

&ODATE

Ordered Date (yy/mm/dd)

&PREFIX

Current TSO Prefix

&RDSN

Current dataset name

&RMBR

Current member name

&RMEM

Current member name

&SDATE

Standard Date (yyyymmdd)

&SMFID

Active SMFID for the LPAR

&SYSNAME

Active LPAR Name

&SYSID 1

Character System Name

&SYSPLEX

Active SYSPLEX Name

&SYSPREF

Current TSO Prefix

&SYSSMFID

Active SMFID for the LPAR

&SYSUID

Current userid

&UDATE

USA Date (mm/dd/yy)

&USERID

Current userid

&USERIDL

Current userid lower case

&WEEKDAY

Day of Week (e.g. Monday)

&YY

2 digit Year

&YYYY

4 digit Year

Selecting Records to Execute under RUNC

Using the RUNC command

In the Edit session each record that has a command is eligible to be executed. Those records that are excluded and either are not comments or for which the ‘n’ option was used to skip over the comments, may be executed. The way they are executed is by selecting the row by:

1. Select an individual row using the line selection option of either C or S.

1. C for command or S for Selection – they are synonymous

2. Select a range of rows using CC for the first and CC for the last. Or SS if you prefer.

3. Use the –A, -AL, or –ALL, option on RUNC

1. RUNC -A

4. Use the ONLY option on RUNC in combination with –A or –ALL

1. RUNC –A ONLY(XYZ)

5. Exclude all rows that you don’t want to execute and then use –A or –ALL

ERC

ERC was developed to speed access to the commands dataset or member without forcing the user to navigate multiple ISPF panels. ERC can be used from any ISPF Panel as it is implemented in the site ISPF command table.

The first time ERC is used the user will be prompted to enter the name of a command dataset, typically a PDS. This PDS must already be allocated. It can be Fixed Block or Variable Block and an LRECL of your choice.

If the dataset name does not begin with the users prefix then the dataset, or member, will be opened using ISPF View. This is to enable a shared command dataset and prevent accidental updates.

If the dataset name does begin with the users prefix then the dataset, or member, will be opened using ISPF Edit.

ERC Command Syntax

Option

Description

Blank

Default processing

? or HELP

Display the ISPF Tutorial for RUNC

/SET

Prompt to change the command dataset

-E

Open using Edit

Member-name

A member name or member mask.

If a specific member then that member will be opened.

If a mask then the member list will be presented.

Samples

Some sample commands.

TSO

* list current allocations (status history sysnames)

lista sta hi sys

* listd dataset

listd +      /* prompt for a dataset for listd

&dataset

* listd dataset and members

listd &dataset mem

* Allocate a FB PDSE

alloc ds(&pdsedsn) new spa(&prim,&sec) tr +

recfm(f b) lrecl(&lrecl) blksize(0) +

dsntype(library,2) maxgens(&maxgen) dsorg(po)

* Backup sample.exec and sample.panels

* ** requires the pdsegen application

del sample.exec.j&julian

%pdsegbak sample.exec sample.exec.j&julian backup

del sample.panels.j&julian

%pdsegbak sample.panels sample.panels.j&julian backup

z/OS

* z/OS Commands Sample Command Member

* ejes is used for action commands (change to sdsf if needed)

* cons is used for display commands (change to sdsf if needed)

*

** If your shop uses ejes invoke RUNC -2 on the following command

*  edit c ejes sdsf all

*  edit c cons sdsf all

* Display IPL Info

cons d iplinfo

cons d u,iplvol

* Display MVS Allocation Settings

cons d alloc,options

* Display Catalog Info

ejes f catalog,report,cache

ejes f catalog,report,performance

EDIT

//JOBNAME  JOB ACCOUNT,&USERID,

//         NOTIFY=&USERID,MSGCLASS=R

//*

//* TO USE THIS JCL ISSUE THE EDIT COMMAND RUNC 4 ON THE NEXT 2 RECORDS

//* EDIT C EXECLIB &EXEC ALL

//* EDIT C TSOCMD  &TSOCMD ALL

//*

//* NOTE: THE EDIT COMMAND WILL ALSO BE CHANGED BY THE RUNC

//*

//TMP      EXEC PGM=IKJEFT1B,DYNAMNBR=50

//SYSEXEC  DD DISP=SHR,DSN=EXECLIB

//SYSTSPRT DD SYSOUT=*

//SYSTSIN  DD *

TSOCMD

/*

JES2

* Sample JES2 operator commands

*

** Prefix with either EJES or SDSF depending on which you use

*

** If your shop uses ejes invoke RUNC -2 on the following command

*  edit c sdsf ejes all

*

*  Display JES2 job definitions

sdsf $djobdef

*  Display all jobs which occupy more than 5% of the spool

sdsf $djq,spl=(%>5)

*  Display all jobs on the print/punch queue more than 5 days old

sdsf $djq,a>5,q=ppu

JES3

*

** JES3 Commands

*

*

** Prefix with either EJES or SDSF depending on which you use

*

** If your shop uses ejes invoke RUNC -2 on the following command

*  edit c sdsf ejes all

* Display Main Processor info

ejes *i,main=all

ejes *i,main=&main

* Display Active Jobs

ejes *i,a

ejes *i,a,&main

ejes *i,j=&jobname

ejes *i,j=&jobnumber

OMVS

* ---------------------------------------- *

* This is a set of sample omvs commands    *

* to demonstrate some of the capabilities. *

* ---------------------------------------- *

* find a file by name

omvs su;find &dir -name '&filename'

* find file in /u/files.all

omvs grep '&string' /u/files.all

Documentation

cons d iplinfo

<doc>

<title>Title Text on &lpar

This is a test &date on lpar &lpar

After viewing this documentation SYS1.PARMLIB member

IEASYS00 will be presented in ISPF View.

</doc>

view dataset('sys1.parmlib(ieasys00)')

Table of Contents

Change History

Introduction

What is RUNC?

What benefit does RUNC provide?

RUNC

RUNC Command Syntax

RUNC Command Options

RUNC Defaults

Format for Commands

Command Types and Syntax

Documentation

Using the <START> and <END> statements

Using the <EXIT rc> statement

Workflows

Symbolics

Selecting Records to Execute under RUNC

Using the RUNC command

ERC

ERC Command Syntax

Samples

TSO

z/OS

EDIT

JES2

JES3

OMVS

Documentation