Installing and configuring Rational Developer for System z File Manager
IBM® File Manager for z/OS™ is a member of the IBM Problem Determination Tools suite, which provides comprehensive tools for working with OS/390® data sets, DB2® data, IMS™ data, and CICS® data. These tools include the familiar browse, edit, copy, and print utilities found in IBM® ISPF for z/OS®, enhanced to meet the needs of application developers (see the Resources section for further information about IBM File Manager for z/OS).
IBM® Rational® Developer for System z™ Version 7.1’s File Manager feature integrates with IBM File Manager for z/OS to provide application developers with the ability to browse and edit sequential data sets, partitioned data set members, and Virtual Storage Access Method (VSAM) data sets of type key-sequenced data set (KSDS) and entry-sequenced data set (ESDS) in a workstation Rational Developer for System z environment. It can show records formatted according to field layouts typically provided by COBOL copybooks or PL/I include files.
This article will demonstrate the process needed to use the Rational Developer for System z File Manager feature to edit a data set. It assumes prior knowledge of both IBM File Manager for z/OS (see the related library here) and IBM Rational Developer for System z (see the related library here). It will explain the steps needed for you to configure Rational Developer for System z File Manager so that it can communicate with IBM File Manager, and will then provide an example of using the Rational Developer for System z File Manager Formatted Data Editor to edit a KSDS.
System z installation and configuration
In order to use the File Manager feature of Rational Developer for System z, IBM File Manager for z/OS V8.1 (program number 5655-S14) needs to be installed on your system. Refer to the IBM File Manager for z/OS User’s Guide and Reference for further information (SC19-1239-00). Once it has been installed and configured, the Rational Developer for System z V7.1 host components (Refer to Host Configuration Guide V7.1 – SC23-7658-00) must also be installed and configured.
As described in the Rational Developer for System z host components configuration guide, the following items in the configuration file (FMIEXT.properties) need to be customised to suit your installation (the default location of this file is /usr/lpp/wd4z/rse/lib under UNIX System Services directory):
- Startup.script: The absolute location of fmiSub. The default location is /usr/lpp/wd4z/rse/lib/
- Startup.port: The start of the Rational Developer for System z File Manager server port range. When Rational Developer for System z File Manager is starting up an instance of IBM File Manager for a dataset browse or edit session, it opens a socket over which Rational Developer for System z File Manager and IBM File Manager will communicate. This is the first port that will be checked for availability.
- Startup.range: The size of the port range. If the port defined as Startup.port is unavailable, Rational Developer for System z will iterate through <Startup.range> ports and open its socket using the first available port.
- Startup.fmload: The absolute location of the IBM File Manager load library (for example, FMN.SFMNMOD1).
- Startup.jobcard: The job card for the JCL Rational Developer for System z will use to start an IBM File Manager job. This should be customized to suit your system.
- Startup.sysout: The SYSOUT class for Rational Developer for System z File Manager's startup JCL.
The Rational Developer for System z File Manager feature is selected for installation by default as part of Rational Developer for System z installation. Ensure that the Rational Developer for System z File Manager feature is selected, as shown in Figure 1.
Figure 1: Select Rational Developer for System z File Manager feature for installation
Create and open data set records using Rational Developer for System z File Manager
This section demonstrates the basic steps for you to browse and edit records stored in a data set using Rational Developer for System z File Manager. In particular, it shows you how to specify the record format of the data stored in a KSDS using a COBOL copybook. The basic steps described in this section should be the same in principal for other types of data sets (such as VSAM files), and when specifying the record format of the data using a PL/I include or IBM File Manager for z/OS template instead of a COBOL copybook.
1. Create a data set containing sample data
In this step, you create a KSDS containing name and address information of various people living in Australia. Submit the existing Job Control Language (JCL) in KENICHI.TEST.JCL(BLDVSAM) to create the new dataset. Figure 2 shows the BLDVSAM member being edited in the Rational Developer for System z Live Parsing Extensible Editor (LPEX). Note that the key is defined to start at position 0 and have length 6 ( KEYS(6 0) ).
Figure 2: JCL to create key-sequenced data set
2. Create a copybook to describe the record format
In this step, create a COBOL COPYBOOK that describes the format of records stored in the sample data set. The sample COBOL COPYBOOK is shown in Figure 3 in the Rational Developer for System z System z LPEX Editor. The sample COPYBOOK is a member of the partitioned data set called KENICHI.TEST.COBOL.COPY named MYDATA. Note that all of the fields are defined as alphanumeric (PIC X) except for the first one, which is defined as being zoned decimal (PIC 9). The first field also happens to be the key field, and has length six to match the KSDS that you created previously.
Figure 3: COBOL to define key-sequenced data set record layout
3. Specify z/OS file mapping for the sample data set
In the Remote Systems view under MVS files shows a list of data sets with different icons to indicate different types of data sets (and their associated editors) when you choose to browse a data set. The association of a data set name and its preferred editor is specified in the z/OS File System Mapping view shown in Figure 4.
Figure 4: File association for z/OS files
By default, mainframe datasets matching the pattern
**DATA will be given the
tdat extension when being displayed in the Remote Systems view. If you browse the file associations for .tdat files (Window > Preferences > General > Editors > File Association), you see a default of Formatted Data Editor. The data within these files will be displayed with the Rational Developer for System z File Manager Formatted Data Editor by default. In addition to editing .tdat files, the Formatted Data Editor will also be used to edit VSAM clusters by default (whether or not they have the .tdat extension), because it is the only Rational Developer for System z editor currently capable of editing VSAM cluster data.
If the default mappings do not match the naming conventions of your data sets, you may add custom mappings as well. It is not necessary in this case, because the data set that you have created is a VSAM cluster, and it matches the
**DATA pattern, with both of these conditions causing the data set to be opened in the Formatted Data Editor. However, you will add a mapping as an example.
In the z/OS File System Mapping view, right-click and select Add Data Set Mapping. Enter
KENICHI.MYVDATA as the mapping criterion and
tdat in the Other textbox under Workstation File Extension. Notice that the sample data set (KENICHI.MYVDATA) now has .tdat as its preferred workstation file extension. If there are a few data sets that still do not have the correct workstation file extension, the file extension may be forced by editing the Extension field in the Mapping panel of the data set’s Properties dialog.
4. Specify the data set’s record layout
The Formatted Data Editor needs to know the format of records stored in a data set in order to display the contents in a meaningful way for application developers. In this scenario, use the COBOL COPYBOOK created in the previous step to describe the data.
Right-click the KSDS containing the sample data (KENICHI.MYVDATA) and select Properties. This brings up the Properties dialog for the selected data set shown in Figure 5.
Select Template Association. In this view, you can either specify the full name of template to use for the selected data set, or browse through the data sets available in your Remote Systems filter for the current target system. In this case, KENICHI.TEST.COBOL.COPY(MYDATA) is selected.
Figure 5: Template association for the selected data set
In addition to using COBOL COPYBOOKs to specify the record layout, you can also use PL/I include files and IBM File Manager templates. IBM File Manager templates are derived from COBOL COPYBOOKS and PL/I includes by compiling them under ISPF, and they may contain additional information (such as identification and selection criteria).
When you browse for templates in the Template Association panel (shown in Figure 5), you may select the Known Templates and Copybooks only option to filter out all data sets that do not currently have the workstation file extensions for COBOL copybooks, PL/I includes, or IBM File Manager templates. In the Rational Developer for System z File Manager user interface and documentation, template is typically used as a generic term to refer to all three of these dataset types. Refer to the IBM File Manager User’s Guide for further information about templates.
5. Opening the data set in the Formatted Data Editor
Right-click the sample data set (KENICHI.MYVDATA) and select Open With > Formatted Data Editor. A progress dialog will appear while an IBM File Manager for z/OS edit session starts for the requested data set. Once the IBM File Manager for z/OS edit session has begun and the Formatted Data Editor has retrieved the initial data for the edit session, the Formatted Data Editor will appear (Figure 6).
Figure 6: Record data display using the Formatted Data Editor
Editing the data record
Before you edit the data record, it will help if you understand how the Formatted Data Editor is configured.
Table and single modes
Notice that, in the default Formatted Data Editor interface shown in Figure 6 previously:
- The template that provides the record layout for the session is listed near the top after Template Associated
A tabular view of the data is provided below the name of the template that has been associated. This is called the Table mode.
- Each row in the table represents one record in the data set.
- The fields within each record are formatted correctly in columns, with the appropriate headings for each column being based on the information specified in the COBOL COPYBOOK.
- As defined when you created the KSDS, the first field contains the KSDS key. To better highlight them, key fields are displayed in blue instead of black.
The first field also displays in a simplified numeric format. For example, the first field actually contains
000100, but this has been simplified to
100for display because this is a zoned decimal field.
A single record’s data is displayed at the same time in the lower part of the editor. This is called the Single mode.
- All modes are synchronized. Changes made in one mode will be immediately reflected in all others.
- Single mode may be removed from the view by clicking the button that is circled in Figure 6. Its size with respect to the table mode may also be changed by dragging the divider between them up or down.
- The up and down buttons on the right side of the single mode will move the selected record up or down. The change in selection will also display in the table mode.
At the bottom-left of the editor, there are two tabs. By default Table/Single is selected. By clicking the tab marked Character, you enable Character Mode. When in Character Mode, as shown in Figure 7, the records are treated as if they contain exclusively alphanumeric data. The record layout described in the template is not applied to the records. If data in the records is not alphanumeric, and it cannot be displayed as such, a box character will appear to represent the non-displayable character.
If a data set is opened without a template being associated with it, the table mode will display data in the same way as character mode does for all data sets. Since this mode is less useful for basic editing operations, the article will return to the Table/Single tab for the rest of the example.
Figure 7: Character mode
In Table and Character modes, the record layout field metadata displays when you point at the column header. In Figure 8, you can see the following about the first field:
It is field #2 from the associated copybook,
- It is a zoned decimal field (ZD)
- It starts at position 1 in the dataset
- It is 6 bytes long
- It contains KSDS key data
Likewise, if you point at
LASTNAME, you can see that it is field #4 from the copybook, that it is alphanumeric (AN), that it starts at position 8, and that it is 18 bytes long.
Figure 8: Field metadata
Editing a field
To edit a field, simply select it with the mouse, and modify the contents. In the current example, changes to the first field must be numeric. If invalid data is entered for a given field type, the error will display near the top of the editor as shown in Figure 9. If there is an error in the entered data, you cannot save the change to the field. The field contents will be reverted to their previous value if you press enter while there is an error in a field.
Figure 9: Error in field
If the new contents of the field are valid, the change will be allowed and maintained. For this example, change the second record’s MYKEY field from 20 to 25, as shown in Figure 10. Note that the single mode has been updated to show the new values for the record, as expected, and that the name of the data set on the editor tab at the top left has an asterisk beside it. The asterisk denotes that the editor is "dirty." This means that there are pending changes that have been made to the data, but that have not been saved back to the data set itself. Until you perform a save operation (File > Save), the data set and the data in the current edit session are out of sync.
Figure 10: Edited record
You can display and edit the underlying hexadecimal data by clicking the circled button in Figure 11. The hexadecimal representation of the data is displayed below each record such that the two byte nibbles are directly underneath the respective byte in the main record display. This is the same way that, by default, the hexadecimal displays in IBM File Manager.
Figure 11: Hex editing
You can edit the hexadecimal representation. You can even force invalid values for field types (for example, an alphabetic character in a zoned decimal field) into a field by editing the hexadecimal representation. If a field contains an invalid value for its specified type, its display representation becomes a series of asterisks, as shown in Figure 12.
Figure 12: Forcing invalid field content using hex editing
Very large data set support
Some data sets may be large enough that they will not fit in the workstation’s available system memory. To allow you to edit such large data sets, the Formatted Data Editor pulls one subset of the records in the target data set at a time. The records currently in the editor are known as the editor’s window of the data set. The default window size is 200 records.
Two buttons are provided at the top of the Formatted Data Editor that can be used to move the editor’s window of the data set, as shown in Figure 13. Moving the window up or down is also referred to as stepping through the data set. By default, the window step size is 50 records.
Figure 13: Formatted Data Editor Move Window buttons
The current position in the dataset is shown at the bottom of the editor. The format of the display is:
Records <top window record number> - <bottom record number> (<total number of records>)
In Figure 14, records 21-40 out of 774 are currently being displayed.
Figure 14: Formatted Data Editor window position information
What you have learned
In this article, you have learned how to use the Rational Developer for System z File Manager feature to edit a data set. You followed the steps necessary for you to configure Rational Developer for System z File Manager so that it can communicate with IBM File Manager, and then used the Rational Developer for System z File Manager Formatted Data Editor to edit a KSDS.
We would like to thank Barry Cresswell and Peter Costigan for reviewing the early draft version of this article.
- Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
- Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
- Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
- Browse the technology bookstore for books on these and other technical topics.
- Refer to the File Manager for z/OS page for further information about IBM File Manager for z/OS.
- Rational Developer for System z File Manager Viewlets
- IBM File Manager for z/OS™ documentation library
- IBM Rational Developer for System z documentation library
Get products and technologies
- Download trial versions of IBM Rational software.
- Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.