The IBM Developer for z Systems (IDz) V14.1 release introduces support for ISPF Edit Macros. This new feature is accessible to the IDz V14.1 end users through a new action on Menu Manager, which can be invoked within an IDz editor session, from the Remote Systems Explorer view or the z/OS Projects view. This enhancement in the IDz V14.1 workbench contains the following features:

  • The Edit Macro action can be invoked for a Partitioned Data Set (PDS) member as well as for a Sequential Data Set.
  • When invoking the Edit Macro action from the Remote Systems or z/OS Projects view, it is possible to request that the contents be first loaded into an editor window before invoking the Edit Macro action.
  • When invoked from within an IDz editor session, saving the editor contents is not required before invoking the Edit Macro action. This means that it is possible to invoke the Edit Macro for editor contents that have not been saved.
  • When opened in an edit session, after invocation of the Edit Macro action, the contents of the editor are updated with the results of the Edit Macro invocation.
    • The updated editor contents are not automatically saved. This allows the IDz user to analyze the results of the Edit Macro action before saving the editor contents.
    • The IDz user can also decide to undo the results of the Edit Macro action.

In the IDz V14.1 release, support for ISPF Edit Macros is limited to Edit Macros that alter and save the contents of the file being processed. Visual updates (i.e. Exclude lines, etc.) that do not alter the file contents, or unsaved macro updates, are not reflected in the IDz editor when the ISPF Edit Macros are executed from within IDz. For a Partitioned Data Set, the invocation of the ISPF Edit Macro is also limited to a single member, you cannot select the Partitioned Data Set itself to execute the macro against every member contained within.

Invoking an ISPF Edit Macro from IDz V14.1

Access to the ISPF Edit Macros from IDz is provided through the IDz Menu Manager interface. Once the IDz Menu Manager Edit Macro actions are created and made available to the IDz workbench, they can be invoked from any of the following locations:

  • IDz Editor session. Within the editor session, the IDz user can right-click and select the IDz Menu Manager action that was created for the desired ISPF Edit Macro.
  • z/OS Projects and Remote Systems views. The IDz user can select a PDS member or a Sequential Data Set, and then right-click on the resource and select the IDz Menu Manager action that was created for the desired ISPF Edit Macro. If the resource is not currently opened in an editor session, either of the following situation applies:
    • If EDIT is specified as a parameter in the IDz Menu Manager action command, the resource is first opened in an editor, and the ISPF Edit Macro is invoked for the editor contents.
    • If EDIT is not specified as a parameter in the IDz Menu Manager action command, the ISPF Edit Macro is executed for the selected resource without opening it in an editor.

Important considerations when invoking an ISPF Edit Macro from IDz 14.1

When the ISPF Edit Macro is invoked for a resource that is opened in an IDz editor, the most current editor contents (even the unsaved data) are provided to the ISPF Edit Macro that is being executed on the z/OS host environment. If successfully executed, the editor contents are then replaced with the updated data returned by the ISPF Edit Macro execution.

When the ISPF Edit Macro is invoked for a resource that is not opened in the editor, the ISPF Edit Macro is responsible for saving any updates it does, because no data is returned to the IDz workbench.

Information on creating IDz Menu Manager Edit Macro actions is provided in later sections.

Illustrating the invocation of the IDz Menu Manager Edit Macro

The following ISPF Edit Macro, called ADDDISP, inserts a DISPLAY statement with the name of each paragraph in the line that immediately follows the paragraph name in a COBOL program.

Using ISPF Edit Macros from within IDz 14.1 - REXX program that inserts a DISPLAY statement with the name of each paragraph in the line that immediately follows the paragraph name in a COBOL program.

An IDz Menu Manager Edit Macro action can be invoked from an IDz editor, the z/OS Projects view and the Remote Systems view. Here are some examples using an IDz Menu Manager action that includes ADDDISP in a selection list as one of the ISPF Edit Macro that can be invoked.

From within an IDz editor

The following sequence of screen images illustrate the invocation of ADDDISP from an IDz editor. After the execution of ADDDISP, the editor contents are updated with the results. The IDz user can undo those changes, if needed, since the editor contents are in unsaved state.

Using ISPF Edit Macros from within IDz 14.1 - Right-clicking inside an editor to select the ISPF Edit Macro action

Using ISPF Edit Macros from within IDz 14.1 - Dialog for selecting an Edit Macro from a list

Using ISPF Edit Macros from within IDz 14.1 - Editor contents after execution of the Edit Macro

From outside of an IDz editor

The following sequence of screen images illustrate the invocation of the IDz Menu Manager Edit Macro action with the resource not already opened in the IDz editor. This example makes use of the same ISPF Edit Macro called ADDDISP. The resource is first opened in the editor, and after the invocation of ADDDISP, its contents are replaced with the ISPF Edit Macro results. The IDz user can undo those changes, if needed, since the editor contents are in unsaved state.

Using ISPF Edit Macros from within IDz 14.1 - Right-clicking on a program in the Remote Systems Explorer view to select the ISPF Edit Macro action

Using ISPF Edit Macros from within IDz 14.1 - Dialog for selecting an Edit Macro from a list

Using ISPF Edit Macros from within IDz 14.1 - Editor contents after the program is loaded into the editor window and the execution of the Edit Macro

IDz client setup for using the ISPF Edit Macro

Access to ISPF Edit Macros from IDz is done via the IDz Menu Manager interface. This is a one-time setup for most cases. It is possible to create a single IDz Menu Manager action that contains a list of ISPF Edit Macro names from which the IDz user can select. The IDz Menu Manager Edit Macro actions can be distributed to other IDz users who can then invoke them as needed.

There are many ways to add a Menu Manager action to an IDz workbench. One of the ways in IDz V14.1 is to follow the steps listed here.

  1. Select Window > Preferences > Menu Manager > Actions and Menus.
  2. In the Actions and Menus Preferences page, click on the “New Local/Remote Action…” button.
  3. In the New Action page, specify the name of the action, for example “ISPF Edit Macro”. Then, click Next.
  4. In the File Associations page, select the file type to associate with the action, for example “Add all”. Then, click Next.
  5. In the Data Set Filters page, optionally specify any data set filter. Then, click Next.
  6. In the Run Options page, fill in the following information:
    1. In the command text area, specify the parameters that are needed by the IDz Menu Manager Edit Macro command. More details on these parameters are available in the next section.
    2. In the Action Properties section, select the checkbox for “Show on generic menu”.
    3. In the Action Properties section, select “Use existing action” and then click the “Select…” button next to “ID:”.
      In the Action Selection page, under com.ibm.ftt.ui.menumanager, select com.ibm.ftt.ui.menumanager.edit.macro.action and then click OK.
    4. Click Finish.
    5. Click OK to exit the Preferences page.

Refer to the IDz Menu Manager documentation and also the References section at the end of this article for more detailed IDz Menu Manager scenarios, such as creating menus, submenus, user prompts, selection lists, etc..

IDz Menu Manager Edit Macro command parameters

During the definition of the Menu Manager Edit Macro action, you must specify parameters that are passed to the Edit Macro command. These parameters are described in this section. Many of these parameters are passed to a REXX program on the host which drives the invocation of the ISPF Edit Macro.

The format of the parameters is specified in a single line as follows:

<Edit Option>!<Work Data Set>!<Allocation Parameters> + <Additional Allocation Parameters>!<IDz REXX Data Set>(FELEDTMC)!<Edit Macro Data Set>(<Edit Macro Name>)!<Edit Macro Parameters>

where

  • The exclamation character (!) is used to separate the different parts of the command, explained here. It can be surrounded by blanks to improve readability.
  • <Edit Option>, when set to EDIT, indicates that the user wants the IDz Menu Manager action to open the data set member in the editor if it was not already opened when the Menu Manager action was invoked. When not specified, or something other than EDIT is specified, the ISPF Edit macro is directly executed against the selected file, without opening it in the editor.
  • <Work Data Set> is the name of a data set with the same characteristics as the data set holding the file being processed by the ISPF Edit Macro action. This data set will be allocated if it does not exist. If a single period (.) is provided as value, then a data set name is generated for you.
  • <Allocation Parameters> are optional allocation parameters to override the defaults used during the allocation of the work data set. When provided, the values must be valid arguments for the TSO ALLOCATE command. This should only be specified if an override value is required.
  • <Additional Allocation Parameters> are for additional, non-standard, parameters to pass to the REXX program during the allocation step. This group of parameters must be preceded by the plus sign (+) when used. In IDz V14.1, the only supported parameter is “STATS”, to force the creation of ISPF statistics for work data set members.
  • The ISPF Edit Macro action interacts with a REXX program on the host. <IDz REXX Data Set> is the name of the data set that contains this REXX program. IDz provides the sample FELEDTMC REXX for this purpose.
  • <Edit Macro Data Set> is the name of the data set that contains the ISPF Edit Macro that is to be invoked.
  • <Edit Macro Name> is the name of the ISPF Edit Macro that is to be invoked.
  • <Edit Macro Parameters> are the parameters that are to be passed to the ISPF Edit Macro. Up to 26 single-word arguments can be provided to the macro. These arguments will be VPUT’d as FELEDITA->FELEDITZ respectively. The macro can then use VGET to get the value.

Special notes on JCL-style variables

Usage of JCL-style variables is supported for all arguments. Note that + must be used instead of the usual & character. This restriction is because the IDz Menu Manager actions are stored in XML format, and the & character has special meaning in XML. For example, specify +SYSPREF. instead of &SYSPREF..

The following variable names are supported:

  • +FELDATE. is converted to Dyyyyddd (7 character Julian date)
  • +FELTIME. is converted to Thhmmss (hour minute second)
  • +SYSUID. is converted to the user ID
  • +SYSPREF. is converted to the TSO prefix
  • any system symbol defined in PARMLIB(IEASYMxx) written in +. style is converted to the related value

Additionally, IDz Menu Manager variables are also supported.

Example IDz Menu Manager Edit Macro commands

An example command text area is shown here:

EDIT ! $userid.STAGING.DATASET($name) ! + STATS ! FEL.SFELSAMP(FELEDTMC) ! EDIT.MACRO.REXX(TIMESTMP) ! +SYSNAME +FELDATE +FELTIME IDz

In this example, the IDz Menu Manager action is associated with a single ISPF Edit Macro, TIMESTMP, which receives the system name, current date and time, and ‘IDz’ as parameters. We also explicitly specify which data set should be used as the work data set.

Another example command text area is shown here:

EDIT ! .! + STATS ! FEL.SFELSAMP(FELEDTMC) ! EDIT.MACRO.REXX($input(Select ISPF Edit Macro to invoke,,$list{CPYRIGHT,ADDDISP,DELDISP})) !

In this last example, the end user will be prompted with a list (CPYRIGHT, ADDDISP, DELDISP) from which to select the ISPF Edit Macro that is to be invoked for the action. The ISPF Edit Macro action will generate the work data set name.

One thing to note is that the value specified for the ISPF Edit Macro name, whether by itself or in a list of names, is not validated by the IDz client. For example, specifying a ISPF Edit Macro PDS member name that is longer than 8 characters, while not valid, will not generate an error on the IDz client side. When the action is executed, this will generate an error on the host because of the invalid PDS member name.

Example screen images for the creation steps of a Menu Manager Edit Macro action

The following sequence of screen images illustrate the steps for creating an IDz Menu Manager Edit Macro action.

Using ISPF Edit Macros from within IDz 14.1 - Selecting Window > Preferences to open the Preferences page” width=”640″ height=”480″ class=”alignnone size-medium wp-image-9370″ /></a> </p>
<p><a href=Using ISPF Edit Macros from within IDz 14.1 - Selecting Menu Manager from the Preferences list items and clicking on the New Local/Remote Action button

Using ISPF Edit Macros from within IDz 14.1 - Providing the Menu Manager action name from the New Action Page dialog of the Menu Manager New Action Wizard, and then click Next

Using ISPF Edit Macros from within IDz 14.1 - Dialog for selecting the file types to be associated with this action, and then clicking Next

Using ISPF Edit Macros from within IDz 14.1 - Dialog for specifying the data set filters, if any

Using ISPF Edit Macros from within IDz 14.1 - Dialog for specifying the Run options for the Menu Manager action

Using ISPF Edit Macros from within IDz 14.1 - Dialog for selecting the Menu Manager Edit Macro Action

Using ISPF Edit Macros from within IDz 14.1 - Dialog for specifying the Run options for the Menu Manager action with the Menu Manager Edit Macro action specified

Using ISPF Edit Macros from within IDz 14.1 - Menu Manager main Preferences page after creating the new Edit Macro Action

IDz host setup for using the ISPF Edit Macro

The IDz V14.1 Menu Manager Edit Macro action requires the use of a REXX program to invoke the ISPF Edit Macro. IDz supplies sample REXX program FELEDTMC that can be used right out of the box for this purpose. However, there might need to be some adjustments to the FELEDTMC REXX program to conform with site standards and requirements. The following information is important to help understand the architecture of the REXX program.

  • When an ISPF Edit Macro is invoked against a file open in an IDz editor, the editor contents are copied to a work data set, and the ISPF Edit Macro processes this work data set. Once processing is complete, the content of the updated work data set replaces the original editor contents. The original host file is not updated in this process.
  • The work data set shares the same data set characteristics as the one currently being edited, and is allocated automatically if it does not already exist.
  • The record format and length of the data set being edited may vary from one edit session to the next. In this case, each session will use their own work data set.

Understanding the FELEDTMC REXX program

The FELEDTMC REXX program plays the intermediary role between the IDz client and the host in the processing of the ISPF Edit Macro. Therefore, it is important to understand the different steps that are involved, and when the REXX program is invoked for each of those steps.

    IDz depends on the FELEDTMC REXX program to provide three essential functions, each with its set of required parameters.

  • Allocate – To allocate the work data set and to return the name of the allocated data set.
  • Execute – To execute the ISPF Edit Macro command.
  • Cleanup – To perform any necessary cleanup of the work data set.

The FELEDTMC REXX program’s main parameters are in the format:

<command> <command-parameters>

where:

  • <command> is either: ALLOCATE, EXECUTE, or CLEANUP
  • <command-parameters> contain the parameters required for the corresponding command.

ALLOCATE command

For the ALLOCATE command, <command-parameters> has the following format:

< work-dataset> <model-dataset> <optional-parameters>

where

  • < work-dataset> is a required parameter, which is the name of data set that will be used to stage the editor contents being processed during the EXECUTE step. Its format can be either:

    • dataset – if a sequential data set is to be allocated.
    • dataset(member) – if a partitioned data set member is to be allocated.
    • . – a single period character, which indicates that the name is to be generated by the REXX program.
  • <model-dataset> is a required parameter, which is the name of data set that is selected by the IDz client user, and which is to be used as a model for the creation of the work data set. Its format can be either:

    • dataset – for a sequential data set.
    • dataset(member) – for a partitioned data set member.
  • <optional-parameters> This optional parameter consists of 2 parts, each optional, that are separated by a + sign. Those 2 parts are as follows:

    • allocation parameters – Allocation options to override the defaults used to create the work data set. What is specified must be valid for the TSO ALLOCATE command.
    • STATS – This optional keyword, when specified, must be STATS. It also must be preceded by a plus (+) sign which separates it from the previous part. When provided, ISPF statistics are enabled for the work data set member. Enabling ISPF statistics for the work data set avoids scenarios where the work data set is treated as being SCLM managed (which in turn can prevent updates to the data set).

EXECUTE command


For the EXECUTE command, <command-parameters> has the following format:

<work-dataset> <macro-dataset-member> <optional-parameters>

where

  • <work-dataset> is a required parameter, which is the name of data set whose contents are being processed by the ISPF Edit Macro. Its format can be either:
    • dataset – for a sequential data set.
    • dataset(member) – for a partitioned data set member.
  • < macro-dataset-member > is a required parameter, which is the fully qualified name of ISPF Edit Macro data set member that is to be executed. Its format is:
    • dataset(member) – The ISPF Edit Macro must be in a partitioned data set member.
  • <optional-parameters> These are optional macro parameter. Up to 26 additional single-word arguments can be provided to the macro. These arguments will be VPUT’d as FELEDITA->FELEDITZ respectively. The macro can then use VGET to get the value.

CLEANUP command

For the CLEANUP command, <command-parameters> has the following format:

< work-dataset> <optional-parameters>

where

  • <work-dataset> is a required parameter, which is the name of data set whose contents were processed by the ISPF Edit Macro. Its format can be either:
    • dataset – for a sequential data set.
    • dataset(member) – for a partitioned data set member.
  • <optional-parameters> These are optional additional cleanup options. Currently not used.

IDz Menu Manager Edit Macro processing flow

When an IDz end user invokes the Menu Manager Edit Macro action, with regards to the FELEDTMC REXX program, the flow is in the following sequence.

  1. IDz invokes the FELEDTMC REXX program to allocate the work data set, with the ALLOCATE command. FELEDTMC then processes the command. If there are no errors in the processing, FELEDTMC returns >FEL_OK,workDsn< for a sequential data set, or >FEL_OK,workDsn(workMember)< for a partitioned data set member, where workDsn and workMember are the data set and data set member name, respectively. If there are errors, IDz displays a dialog with the error messages returned from FELEDTMC. The error messages can also be viewed in the IDz Remote Console View. This step is only invoked if the IDz Menu Manager Edit Macro action is invoked for content that is in the editor when the REXX is invoked.
  2. If there are no errors in the previous step, IDz invokes FELEDTMC with the EXECUTE command. At this stage, FELEDTMC sets up the necessary ISPF environment libraries and invokes the ISPF Edit Macro specified in the parameters.
  3. After IDz updates the editor contents with the results from the EXECUTE step, it invokes FELEDTMC with the CLEANUP command. FELEDTMC performs the necessary cleanup to ensure that the allocated storage is cleaned up as needed. This step is only invoked if the IDz Menu Manager Edit Macro action is invoked for contents that are in the editor when the request was made.

Remote Console View for IDz Menu Manager Edit Macro

The execution of the FELEDTMC REXX program can be monitored in the Remote Console View of the IDz client. This provides a quick way for determining whether the execution of the REXX program is successful. Here is an example output which shows the beginning and the last portion of the output that are generated by the REXX program:

Using ISPF Edit Macros from within IDz 14.1 - Top portion of the Remote Console View for IDz Menu Manager Edit Macro

Using ISPF Edit Macros from within IDz 14.1 - Bottom portion of the Remote Console View for IDz Menu Manager Edit Macro

References

Acknowledgements

Thanks to Dan McCarty, Andrew Tram, Bill Alexander for the suggestions for improving the end user experience.
Also, thanks to Bill Alexander and Ben Horwood for providing the sample REXX ISPF Edit Macro programs that were used for validating this new feature.
Special thanks to Onno Van den Troost for greatly improving the FELEDTMC REXX program which provides much greater flexibility for the Systems Administrators.
Special thanks to Jessie Chen, Jon Gellin, Jeremy Almeter, Onno Van den Troost, Gina Long, and Bill Alexander for their feedback while reviewing this article.

Sample REXX Edit Macro

Some sample REXX ISPF Edit Macro programs used in the examples mentioned above.

Using ISPF Edit Macros from within IDz 14.1 - Sample REXX ISPF Edit Macro program to replace the (c) character sequence with the Copyright symbol

CPYRIGHT

Using ISPF Edit Macros from within IDz 14.1 - REXX program that inserts a DISPLAY statement with the name of each paragraph in the line that immediately follows the paragraph name in a COBOL program.

ADDDISP

Using ISPF Edit Macros from within IDz 14.1 - REXX program that removes the DISPLAY statements that were added by the ADDDISP REXX program.

DELDISP

3 comments on"Using ISPF Edit Macros from within IDz V14.1"

  1. Thank you very much for this article and all the examples. It is really helpful to understand this useful feature much better.

  2. scott cason April 23, 2019

    Is it possible now, or in the future, to allow user input to the ISPF edit macro from the macro itself ( ie: rexx pull or ISPF dialog )?

  3. joelduquene April 26, 2019

    Hi Scott,

    We are investigating how this can be done from the IDz Edit Macro support. We do understand the value of being able to do this.

Join The Discussion

Your email address will not be published. Required fields are marked *