Using Screen Definition II with Rational Team Concert

Store, edit, and build SDF-II objects

Many large companies that use the IBM® z/OS® software have an investment in IBM Screen Definition Facility II (SDF II). Liam Doherty shows how to store SDF II objects and create build definitions for them in IBM® Rational Team Concert™.

Liam Doherty (dohertl@au1.ibm.com), Enterprise Extensions Architect, IBM

author photoLiam Doherty is an IBM Rational Team Concert enterprise extensions architect and an IBM Interactive System Productivity Facility (ISPF) client developer. He has more than 30 years of experience with the MVS operating system. The past 12 years, he has concentrated on source configuration management in Software Configuration and Library Manager of ISPF and Rational Team Concert.



09 July 2013

Introduction

Even though your organization is moving to using new technologies and tools, such as Eclipse, IBM® Rational® Developer for System z and IBM® Rational Team Concert™, you probably still have a considerable investment in existing technologies that run on your IBM® z/OS® system. One example is IBM Screen Definition Facility II (SDF II).

SDF II is a tool that supports the development, maintenance, and re-engineering of screen objects, such as IBM® CICS®Basic Mapping Support (BMS), IBM® IMS™ Message Format Service (MFS) and Interactive System Productivity Facility (ISPF). With SDF II, you draw or paint the screen interactively through its ISPF dialogs and then generate the SDF II objects to get an equivalent BMS map MFS screen or ISPF panel. At the same time, SDF II generates a data structure for each map, which can then be used by the application program.

These are the main tasks that you can perform using SDF II:

  • Design and create screen layouts.
  • Test the layout and appearance of the screens.
  • Generate the maps and the related data structure in the format used by the target system.
  • Build a prototype by combining panels to validate the sequence and the layout of the panels.
  • Maintain existing panels.
  • Migrate panels into SDF II from a target system.
  • Convert panels used in one target system for use in another target system.
  • Print panels.

If you are using a library management system, such as SCLM, to store your SDF II objects, but might be considering moving to Rational Team Concert in the future, then this article explains how these SDF II objects can be stored in Rational Team Concert and built using Rational Team Concert build definitions.

Note:
To follow the steps in this article, you should be familiar with Rational Team Concert and how to set-up both Enterprise Extensions system definitions and build definitions.


Overview of SDF II implementation with Rational Team Concert

Implementing SDF II for use with Rational Team Concert is split into two main areas:

  • Editing SDF II objects so that the SDF II application dialogs are invoked
  • Generating maps and copybooks from the SDF II objects

Because SDF II is an ISPF application, editing SDF II objects can be supported only through the Rational Team Concert ISPF client. Working on SDF II objects through the Eclipse interface is not possible.

There are also some issues in the way that the Rational Team Concert build process invoke the SDF II generation process, because it uses the ISPF gateway to invoke REXX execs during build time. Running the SDF II generate from Rational Team Concert is the same as running the batch SDF II process. However, there is a restriction in SDF II that says that ISPF cannot be active if the generate process is invoked in batch. The ISPF Gateway has already started ISPF when it invokes SDF II, so the generate process will fail, because SDF II will not run under an active ISPF.

This means that you need to create an SDF II invocation exec that runs as a Time Sharing Option (TSO) command, not as an ISPF command, through the ISPF gateway, so that ISPF will not be active. You then need to tell SDF II to start ISPF.

Additionally the DGIPRINT output needs to be available to Rational Team Concert. By default it is allocated and freed within the SDF II execs, so the output messages cannot be captured by Rational Team Concert.

The following subsections give a summary of the implementation steps required for SDF II support in Rational Team Concert.

General tasks

  1. Run the SDF II DGIIXIN1 exec to generate a specific SDF II invocation exec that meets the requirements required by Rational Team Concert.

Edit SDF II objects in Rational Team Concert

  1. Allocate SDF II product libraries
  2. Identifying the SDF II object libraries
  3. Adaption of SDF II supplied user exits
  4. Creation of Rational Team Concert data set definitions for required SDF II libraries
  5. Sharing SDF II members with Rational Team Concert
  6. Editing the SDF II objects in Rational Team Concerts ISPF Client

Build SDF II objects using Rational Team Concert

  1. Creation of a Rational Team Concert invoked REXX exec that will invoke SDF II
  2. Creation of Rational Team Concert data set definitions for output types
  3. Creation of Rational Team Concert translators and language definitions
  4. Assigning languages to parts
  5. Creating a build definition
  6. Building the SDF II objects

General tasks

Prior to setting up Rational Team Concert to interact with SDF II you need to ensure that SDF II itself has been setup correctly. These tasks are covered in this section.

Create a new SDF II invocation exec

This is a standard task for all SDF II invocations. It is covered in Chapter 2 of the SDF II Administrator's Guide.

There are specific reasons for needing to do this however. Out of the box the DGIIXINV exec, or its alias SDF2INV will work OK for online SDF II invocation. However for the batch invocation of the generate you need certain parameters set to allow successful invocation. As such the first task you should perform is the generation of a customized DGIIXINV routine. It specifies such things as:

  • The high level qualifier of your ISPF libraries
  • The ISPF release you are running on
  • The high level qualifier of your SDF II libraries
  • Whether you want SDF II to allocate ISPF in batch mode
  • Whether you want DGIPRINT allocated or not

To invoke this exec in ISPF option 6, on by using the TSO prefix on a command line enter:

ex '<SDF-II HLQ>.SDGICMD(DGIIXIN1)'

If this is the first time that you have run this exec, it will default to certain values. If you have run it before, it will populate the variables with values from the previously generated DGIIXINV exec. Let's assume that this is the first time that you have run this exec.

You need to make several changes to the information in the displayed screens. These changes, use PF7/PF8 to scroll up and down to change the required information:

  1. Change CLIST(DGIIXINV) to a modifiable exec library. The generated exec, along with the SDF2INV alias, will be created there.

    Note:
    The new library you specify must not currently be allocated, for example, to SYSPROC. If it is, then the changes made in the displayed screens will fail to complete successfully.
  2. Specify the high-level qualifier of the SDF II software.
  3. Blank out the TABLES literal.
  4. Blank out the SYSOUT(*) setting for the SDF II print output. This will force SDF II to not allocate DGIPRINT. During the generate process Rational Team Concert will allocate this file so that the output can be trapped.
  5. Change Need ISPF-Allocation to YES. This ensures that the ISPF data sets are allocated during Rational Team Concert build time.
  6. Change the ISPF high-level qualifiers, if required.
  7. Change the profile data set specification to the correct specification for your site.

The panels with required changes are shown in Figures 1 through 3.

Figure 1. Initial invocation of SDF II defaults screen
Changes required on SDF-II defaults screen, part 1
Figure 2. Second part of SDF II defaults screen
No changes required on SDF-II defaults screen part 2
Figure 3. Third part of SDF II defaults screen
Changes required on SDF-II defaults screen part 3

When you press PF3, you will be asked if you want to continue with the generation.

Reply Y, and a new version of DGIIXINV and SDF2INV will be created in the specified library.


Edit SDF II objects in Rational Team Concert

This section takes you through the steps of setting up Rational Team Concert and SDF II so that you can edit SDF II objects directly from the Rational Team Concert ISPF client.

Allocation of SDF II product libraries

The SDF II product data set consists of standard ISPF data sets, such as execs, panels, messages, skeletons, and load modules. For example, the list of libraries might look like this:

SDF2.V1R4M0.SDGICMD
SDF2.V1R4M0.SDGIHPEU
SDF2.V1R4M0.SDGIJCL
SDF2.V1R4M0.SDGILMD
SDF2.V1R4M0.SDGILPA
SDF2.V1R4M0.SDGIMSEU
SDF2.V1R4M0.SDGIPNEU
SDF2.V1R4M0.SDGISAM
SDF2.V1R4M0.SDGISK  
SDF2.V1R4M0.SDGISKEU
SDF2.V1R4M0.SDGITBEU
SDF2.V1R4M0.SDGITUEU

For the SDF II dialogs to be invoked, these libraries need to be allocated to the correct ISPF data definitions. You could do this in your site's logon procedures; however, if you use a more dynamic allocation method for ISPF, you can add these SDF II libraries to the LIBDEF statements in the ISPF client invocation exec that is included with Rational Team Concert. By default, that is BLZ.SBLZEXEC(BLZ). The example in Listing 1 shows the relevant LIBDEF section in the BLZ exec member with the SDF II libraries added.

Listing 1. BLZ exec member with SDF II Libraries added
   /*----------------------------------------------------------------*/
   /* Perform ISPF libdefs and activate alternate EXEC library       */
   /*----------------------------------------------------------------*/
                                                                       
   SDFHLQ = 'SDF2.V1R4M0'                                              
                                                                       
   Address TSO "ALTLIB ACTIVATE APPLICATION(EXEC),                     
                              DATASET('"HLQ".SBLZEXEC')"               
   Address TSO "ALTLIB ACTIVATE APPLICATION(CLIST),                    
                              DATASET('USER.CLIST','"SDFHLQ".SDGICMD')"
                                                                       
   Address ISPEXEC                                                     
   "LIBDEF ISPPLIB DATASET ID('"SDFHLQ".SDGIPNEU',                     
                              '"SDFHLQ".SDGITUEU',                     
                              '"SDFHLQ".SDGIHPEU',                     
                              '"HLQ".SBLZP"LANG"')"                    
   "LIBDEF ISPMLIB DATASET ID('"SDFHLQ".SDGIMSEU',                     
                              '"HLQ".SBLZM"LANG"')"                    
   "LIBDEF ISPSLIB DATASET ID('"SDFHLQ".SDGISK',                       
                              '"SDFHLQ".SDGISKEU')"                    
   "LIBDEF ISPLLIB DATASET ID('"SDFHLQ".SDGILMD',                      
                              '"HLQ".SBLZLOAD')"                       
                                                       
   "QBASELIB ISPPROF ID(PROFDSN)"                      
   If rc = 0 Then                                      
   Do                                                  
      "LIBDEF ISPTLIB DATASET ID("PROFDSN",            
                                '"SDFHLQ".SDGITBEU')"  
      "LIBDEF ISPTABL DATASET ID("PROFDSN")"           
   End
  • Add the SDF II datasets (as shown) to the ISPPLIB, ISPMLIB, ISPLLIB LIBDEF statements.
  • Change SDFHLQ to the high-level qualifier for the SDF II product
  • Add an ALTLIB statement for the CLIST library, similar to the existing ALTLIB for the EXEC allocation. Notice the additional library allocated to the CLIST ALTLIB, called USER.CLIST. This is a modifiable exec library, defined with whatever name you wish, that contains the SDF II user exits that you modify during this process. This exec library is required because these user exits, as included by the SDF II product, do nothing. So you need to concatenate your modified versions in front of the included SDF II versions.
  • The ISPSLIB allocation is not allocated in the normal setup of the BLZ exec, as Rational Team Concert does not include an ISPF skeleton library. You need to add a LIBDEF statement for the SDF II skeleton libraries. Make sure you add a LIBDEF statement to free the ISPSLIB allocation at the end of the BLZ exec member.

Identify the SDF II object libraries

The SDF II object library types have certain default low-level qualifiers that the SDF II execs look for to determine whether the data set being edited is an SDF II data set type. We use the default SDF II data set types in the implementation for this example:

Table 1. SDF II Data set types
SDF II data set typeDescription of data set type
DGIGRP Panel Group
DGIPNL Panel
DGIPST Partition Set
DGITBL AID Table
DGIOCT Control Table

For this implementation example, which is CICS/BMS, use only the DGIPNL and DGIGRP types, which are the most common. These library types are allocated as fixed blocked, record length 80 data sets, and they are populated with sample code. In the DGIPNL data set there is a panel called ORDRMAP and in the DGIGRP data set, a panel group called ORDRSET, that includes the panel ORDRMAP.

Figure 4. ISPF Option 3.4 showing SDF II data set types
Screen capture shows DGIGRP and DGIPNL data sets

Adapt SDF II-supplied user exits

There are several SDF II-supplied user exits that you need to copy and customize for the SDF II invocation to occur for the correct objects. The subsections that follow describe each of these, as well as any updates that are required.

Copy members (DGIIEDT, DGILXIO, DGILXLI) using the same name, from the <SDFII hlq>.SDGISAM library into an exec library that will be allocated to SYSPROC, SYSEXEC, or ALTLIBed in the BLZ exec. In our implementation, this was USER.CLIST

DGILXLI

This exec checks the types of libraries used with SDF II. There are four types of library types possible:

  • ISPF or PDF Libraries
  • SCLM-controlled libraries
  • Externally controlled libraries
  • SCLM-controlled or PDF libraries to be edited by using the edit macro

The final bullet in the previous list is how Rational Team Concert invokes SDF II.

There are no edits to this exec required. It must be concatenated in front of the SDF II product library execs.

DGILXIO

This exec is used to edit SDF II objects directly from the ISPF or PDF editor by using the DGIIEDT edit macro.

There are no edits to this exec required. It must be concatenated in front of the SDF II product library execs.

DGIIEDT

The DGIIEDT EXEC is an edit macro provided by SDF II. It achieves the invocation of the SDF II editor from the ISPF editor. It will be invoked as an initial macro when editing objects through the Rational Team Concert edit function.

There are some small changes that might need to be made to this exec to get it to work correctly, depending on what service level of SDF II you may have applied. What follows is ISPF Edit compare output that shows the changes that may be required

Figure 5. ISPF Edit compare showing the missing */ on line 76
Screen capture, lines 75-78

In the snippet shown in Figure 5, I added a */ after dataset name to correctly complete the comment line.

Figure 6. ISPF Edit compare showing missing */ on line 129
Screen capture, lines 127-131

In the snippet in Figure 6, I added a */ after project to correctly complete the commented-out line of code.

Figure 7. Adding PASSLIB to SDF II invocation
Lines 197-202, PASSLIB keyword added

If you are allocating the SDF II libraries through a LIBDEF statement in the BLZ exec, PASSLIB is required so that SDF II can find all of the required libraries.

The SDF II required execs and macros should now be in place and ready to use. You can now configure the Rational Team Concert side of things.

Create Rational Team Concert data set definitions for required SDF II libraries

Before you can share any SDF II objects in Rational Team Concert, you need to ensure that the data set definitions are created.

Note:
This article discusses the creation of Rational Team Concert definitions specific to SDF II. There are other definitions, for example, the assembler data set definition and data set definitions for existing data sets such as SYS1.MACLIB, that are not covered in this article.

  1. In the Rational Team Concert Eclipse client, under the Team Artifacts view for the required project area, select Enterprise Extensions > System Definitions > z/OS > Data Set Definitions.
  2. Right-click on Data Set Definitions, and select New Data Set Definition.
Figure 8. Creating new data set definitions in Rational Team Concert
new data set definition selected on pop-up menu

You are going to create data set definitions for the DGIPNL and DGIGRP data set types. In the Data Set Definition dialog window, enter the required information:

Name:DGIPNL
Description:SDF II – DGIPNL data set
Usage: Destination data set for a zFolder
Data set name:DGIPNL
Space units: Tracks
Primary quantity:1
Secondary quantity:1
Directory blocks:0
Record format:FB
Record length:80
Block size:32720

Figure 9. Data set definition, DGIPNL
Settings required for DGIPNL data set definition

Create the data set definitions for the DGIGRP data set types by entering the information in the Data Set Definition dialog window, as shown in Figure 10.

Name:DGIGRP
Description:SDF II – DGIGRP data set
Usage: Destination data set for a zFolder
Data set name:DGIGRP
Space units: Tracks
Primary quantity:1
Secondary quantity:1
Directory blocks:0
Record format:FB
Record length:80
Block size:32720

Figure 10. Data set definition, DGIGRP
Settings required for DGIGRP data set definition

Edit the SDF II objects in the ISPF client

You are now ready to test whether your SDF II execs work with the Rational Team Concert ISPF client. The first thing that you need to do to be able to invoke the SDF II dialogs for SDF II objects is activate the DGIIEDT edit macro by specifying it as an initial macro in the edit options screen.

  1. Start the ISPF Client and login to a repository
  2. In the ISPF client primary option menu go to option 3, and in the Source Data Selection panel specify the high-level qualifier (HLQ) where your SDF II object data sets exist.
Figure 11. Specifying HLQ of SDF II objects
Specify sandbox HLQ in Rational Team Concert option 3

This will list your data sets; maybe you have already shared some of your data set types, as I have in my example:

Figure 12. List of matching data sets in the Rational Team Concert ISPF Client
Screen capture shows a list of data sets that match the entered HLQ
  1. From the menu at the top, select Options.
  2. Select 1. Data Set and z/OS UNIX options.
Figure 13. Selecting the Options action bar choice in the Rational Team Concert ISPF Client
Selections for Steps 3 and 4
  1. On the screen display, ensure that the bypass of the z/OS data sets is not selected.
Figure 14. Ensuring bypass of z/OS Data sets is not selected
Turn off Bypass z/OS data set edit options panel

After you have set the initial macro, it will be saved in your profile. You can come back to this option and bypass the z/OS Data Set options panel if you prefer.

  1. Enter an E next to one of your SDF II data sets (the DGIPNL data set, for example), and press Enter to list the members.
  2. In the member list you will see a ? next to the new member. Enter an E next to the member to edit it:
Figure 15. Edit one of the SDF II data sets
Select a DGIPNL member to edit

Because you have said not to bypass the Edit options panel, it will now be displayed.

  1. Enter DGIIEDT as the initial macro.
Figure 16. Enter the name of the DGIIEDT macro
Enter DGIIEDT in the initial macro field

It does not matter that this macro is invoked for all types of members, because the first thing that it does is check whether the type is one of the SDF II types. If it is not an SDF II type the macro is exited.

  1. Press Enter.

At this point, the SDF II dialogs should be invoked so that you can use the SDF II options to manipulate the member. You will first see the SDF II splash screen shown in Figure 17.

Figure 17. SDF II Splash screen
Screen capture of the splash screen
  1. Then press Enter to display the SDF II dialogs,
Figure 18. SDF II dialogs
SDF II selection screen shows editor dialogs

After you have finished editing the panel you, press PF3 to leave the SDF II dialogs and return to the Rational Team Concert ISPF client member list. You are now in a position to share the member.

Share SDF II members with Rational Team Concert

Before you can begin sharing the SDF II objects with Rational Team Concert, you must ensure that they will be shared in binary mode. Given that the SDF II data is not textual, if you were to transfer it to the repository not in binary mode, it would get translated to UTF-8. This might involve certain hex codes being incorrectly assigned, such as hexadecimal 15 line feeds.

  1. In the Rational Team Concert ISPF client primary option panel, and select option 0 (Settings). Make sure that you enter a / (slash) next to "Share files in binary mode."
Figure 19. Select binary mode in Preferences
Preferences window

You need to do this only for sharing the members initially and only for the SDF II objects. After you have shared them, you can set it back again to non-binary mode.

Note:
There is an enhancement request pending to make the binary mode a file property so that individual files can have the property set at share time.

You can now go back to the member and share it with the repository. There is nothing unusual about the share option. Just make sure that you use the correct data set definition for the DGIPNL or DGIGRP. You cannot set the language definition, because you have not created it yet. You'll learn more about that in the next section.


Build SDF II objects using Rational Team Concert

Being able to edit and store the SDF II objects in Rational Team Concert is only half of the story. You need to be able to generate BMS maps and copybooks from the SDF source. The generate action works in two ways, either through the SDF II ISPF dialogs or through the SDF II batch invocation. The batch invocation method is basically how you need to perform the generation through Rational Team Concert.

With the SDF II batch invocation, the JCL allocates all of the ISPF libraries but then invokes the SDF II exec as a TSO command, without starting ISPF. SDF II can then start ISPF internally against the allocated libraries. With the Rational Team Concert build process, if you try to use the ISPF gateway to allocate the ISPF libraries and then start SDF II, it will fail. This is because ISPF is already active, which is a state that is invalid for batch invocation of SDF II.

To get around this, you specified that SDF II would need to allocate ISPF when you created the DGIIXINV invocation exec. This way, you can start the SDF II exec from a TSO command and then let SDF II do the ISPF allocations and start ISPF.

Additionally, there might be times when the default options will not be sufficient for each generation. Therefore, a way of overriding request options needs to be built into the solution. This is covered a bit later in this article.

Create a Rational Team Concert-invoked REXX exec that invokes SDF II

SDF II generation is performed by passing a request file to SDF II that describes what you want done. For this implementation, keep this simple. Generate the request file on the file using parameters specified in the language definition and passed through at build time. To do this, you need to create your own invocation exec that reads these parameters, builds the request file, invokes SDF II, and then captures the returned output to store in the build result, if required.

The REXX exec, called BLZSDF2, performs the following functions:

  1. Allocate SYSPROC so that the SDF II execs can be found. Notice that USER.CLIST is first, because it contains the DGIIXINV(SDF2INV) exec that you generated at the beginning.
  2. Parse the parameters from the build.
  3. Allocate the request file data set.
  4. Allocate the DGIPRINT DD
  5. Allocate an ISPLOG DD.
  6. Allocate and read the Request file option override data set.
  7. Get the name of the data set where the generated copybooks are to be written. This is a data set allocated in the translator, so it's physical name is known only after this exec is invoked.
  8. Get the name of the data set where the generated BMS maps are to be written. This is a data set allocated in the translator, so its physical name is known only after this exec is invoked.
  9. Build the request file.
  10. Call SDF II.
  11. Clean up the Request file.
  12. Print the contents of the DGIPRINT and ISPLOG DDs.
Listing 2. BLZSDF2 exec that performs allocations and calls SDF II
/* REXX */

   Parse Arg DataSet Member Type Lang options

   DGIIIPFX = "SDF2.V1R4M0"

   Address TSO "ALLOC F(SYSPROC) DATASET('USER.CLIST',
                                        '"DGIIIPFX".SDGICMD') SHR"

   Parse Var DataSet Prefix '.DGI' rest

   Say '----------------------------------------'
   Say 'SDF II Generation for member : 'Member
   Say '----------------------------------------'
   Prefix =  "'"Prefix"'"
   Options = Strip(Options)
   Say 'Prefix         : 'Prefix
   Say 'Type           : 'Type
   Say 'Language       : 'Lang
   Say 'Options member : 'Options
   Say '----------------------------------------'
   Say ''

   SDF2_rc = 0

   /* Alloc a request data set to specify the request details */
   x = msg('off')
   Address TSO "FREE  F(BLZSDFR)"
   Address TSO "DELETE '"USERID()".SDF2.REQUEST'"
   x = msg('on')
   Address TSO "ALLOC F(BLZSDFR) UNIT(SYSALLDA) NEW SPACE(1 1) TR",
                    "DA('"USERID()".SDF2.REQUEST')",
                    "RECFM(F B) LRECL(80) BLKSIZE(27920)"

   /* Alloc a DGIPRINT data set                              */
   x = msg('off')
   Address TSO "FREE  F(DGIPRINT)"
   x = msg('on')
   Address TSO "ALLOC F(DGIPRINT) UNIT(SYSALLDA) NEW SPACE(1 1) TR",
                    "RECFM(F B A) LRECL(121) BLKSIZE(27951)"

   /* Alloc an ISPLOG data set                                */
   x = msg('off')
   Address TSO "FREE  F(ISPLOG)"
   Address TSO "DELETE '"USERID()".RTC.ISPLOG'"
   x = msg('on')
   Address TSO "ALLOC F(ISPLOG) UNIT(SYSALLDA) NEW SPACE(1 1) TR",
                    "DA('"USERID()".RTC.ISPLOG')",
                    "RECFM(F B A) LRECL(121) BLKSIZE(27951)"
   /* Get the output COPY data set allocation */
   X = Listdsi("DGICOPY" "FILE")
   DGICOPY = "'"SYSDSNAME"'"
   Say 'DGICOPY='DGICOPY

   /* Get the output BMS data set allocation */
   X = Listdsi("DGIBMS" "FILE")
   DGIBMS = "'"SYSDSNAME"'"
   Say 'DGIBMS ='DGIBMS

   /* Get the SDFIIOPT data set allocation   */
   Opt = 'No'
   X = Listdsi("SDFIIOPT" "FILE")
   /* If allocated then reallocate with the required member  */
   If X = 0 Then
   Do
     SDFIIOPT = SYSDSNAME
     Say "SDFIIOPT ='"SDFIIOPT"'"

     /* Now reallocate it to get the contents  */
     /* of the required option member          */
     Address TSO "FREE  F(SDFIIOPT)"
     x = SYSDSN("'"SDFIIOPT"("Options")'")
     If x = OK Then
       Address TSO "ALLOC F(SDFIIOPT) DA('"SDFIIOPT"("Options")') SHR"
     Else
     Do
       Say 'Options member 'Options' does not exist in data set 'SDFIIOPT
       Exit 8
     End
     "EXECIO * DISKR SDFIIOPT (STEM sdfiiopt. FINIS "
     Opt = 'Yes'
   End
   Else
     Say 'Options data set not allocated'


   If SDF2_rc = 0 then
   Do
     Call BuildReq        /* Build request */
     Call InvokeSDF2      /* call SDF2     */
   End

   x = msg('off')
   Address TSO "FREE  F(BLZSDFR)"
   Address TSO "DELETE '"USERID()".SDF2.REQUEST'"
   "EXECIO * DISKR DGIPRINT (STEM dgiprint. FINIS "
   Do i = 1 to dgiprint.0
     Say dgiprint.i
   End
   "EXECIO * DISKR ISPLOG (STEM isplog. FINIS "
   Do i = 1 to isplog.0
     Say isplog.i
   End
   Address TSO "FREE  F(ISPLOG)"
   Address TSO "FREE  F(DGIPRINT)"
   Address TSO "DELETE '"USERID()".RTC.ISPLOG'"
   x = msg('on')

   Address TSO "FREE F(SYSPROC)"

Exit SDF2_rc

Buildreq:

  /* Build default request options */
  SDF2req.  = ''
  SDF2req.1 = "IIVREQ   = 'G'    /* requests generation              */"
  SDF2req.2 = "IIVNAM   = '"Member"'"
  SDF2req.3 = "IIVLIB   = '*'    /* uses search order                */"
  SDF2req.4 = "IIVTYP   = '"Type"' /* panel or group etc             */"
  SDF2req.5 = "IIVMOD   = ''     /* gen for object's target system   */"
  SDF2req.6 = 'ILV10L01 = "'Prefix'"'
  SDF2req.7 = "ICV10GDS = 'Y'    /* generates a data structure       */"
  SDF2req.8 = "ICV10GCB = 'Y'    /* generates a control block source */"
  SDF2req.9 = "ICV10DLA = '"Lang"' /* programming language           */"
  SDF2req.10= "ICV10DAL = 'N'    /* gen unaligned data structure     */"
  SDF2req.11= "ICV10DGR = 'N'    /* gen no GRAPHIC declarations      */"
  SDF2req.12= "ICV10DTR = 'N'    /* gen no TRIGRAPH declarations     */"
  SDF2req.13= "ICV10DUE = ''     /* invokes no user exit routine     */"
  SDF2req.14= 'ICV10DOL = "'DGICOPY'"'
  SDF2req.15= "ICV10DOD = ''     /* identifies no ddname             */"
  SDF2req.16= "ICV10CDT = '*'    /* gen control block source for all */"
  SDF2req.17= "ICV10CUE = ''     /* invokes no user exit routine     */"
  SDF2req.18= 'ICV10COL = "'DGIBMS'"'
  SDF2req.19= "ICV10COD = ''     /* identifies no ddname             */"
  SDF2req.20= "ISPFIASK = 'Y'    /* Do ISPF allocations              */"
  SDF2req.21= "ISPFILVL = '6.1'  /* ISPF Level                       */"
  SDF2req.22= "ISPFIPFX = 'ISP'  /* ISPF Prefix                      */"
  SDF2req.23= "ISPFILNG = 'EU'   /* ISPF language                    */"
  SDF2req.24= "DGIIIPFX = "SDF2.V1R4M0"  /* SDF2 prefix              */"
  SDF2req.0 = 24

  If Opt = 'Yes' Then
  Do
    /* Override any default options with options from options file */
    Do I = 1 to sdfiiopt.0
      Found = 'No'
      Do J = 1 to SDF2req.0
        If Word(sdfiiopt.i,1) = Word(SDF2req.j,1) Then
        Do
          SDF2req.j = sdfiiopt.i
          Found = 'Yes'
          Leave
        End
      End
      /* If not found add the option to the end */
      If Found = 'No' Then
      Do
        SDF2req.0 = SDF2req.0 + 1
        x = SDF2req.0
        SDF2req.x = sdfiiopt.i
      End
    End
  End

  Say ''
  Say 'SDF2 request options used'
  Do i = 1 to SDF2req.0
    Say SDF2req.i
  End
  Say ''

  Address TSO "EXECIO * DISKW BLZSDFR (STEM SDF2req. FINIS)"

Return

InvokeSDF2:

   sdf2inv = "%SDF2INV REQUEST(SDF2X) "        ||,
             "DSN('"USERID()".SDF2.REQUEST') " ||,
             "LANGUAGE(ENGLISH)"
   Address TSO sdf2inv

   SDF2_rc = rc

Return

This exec is invoked by the required language definition.

Create Rational Team Concert data set definitions for output types

The output types generated from SDF II are BMS map sources and copybooks. You have used existing data set definitions for both of these that are defined as Figure 20 and 21 shows.

Name:BMS Generated Copybooks
Description:Copybooks generated from BMS assemble
Usage: Destination data set for a zFolder
Data set name:BMSCOPY
Space units: Cylinders
Primary quantity:1
Secondary quantity:1
Directory blocks:0
Record format:FB
Record length:80
Block size:0

Figure 20. Create the data set definition for BMS copybooks
Settings for BMS copybook data set definition

Name:BMS Maps
Description:BMS maps generated from BMS assemble
Usage: Destination data set for a zFolder
Data set name:BMS
Space units: Cylinders
Primary quantity:1
Secondary quantity:1
Directory blocks:0
Record format:FB
Record length:80
Block size:0

Figure 21. Create the data set definition for BMS maps
Settings for BMS Maps data set definition

Create Rational Team Concert data set definitions for the override data set (if required)

If there is a possibility that certain SDF II request file options might need to be overridden, a fixed blocked 80 physical PDS(E) should be allocated on the z/OS system that is performing the build. Thus, you now need to create a Rational Team Concert data set definition to reference this data set. Use a data set name that matches your systems naming conventions.

Name:SDF II Options
Description:File containing SDF II generation options
Usage: Existing data set used for build
Data set name:JAZZ00.DEV2.SDFIIOPT
Space units: Blocks
Primary quantity:1
Secondary quantity:1
Directory blocks:0
Record format:FB
Record length:80
Block size:80

Figure 22. Data set definition for the SDF II options file
Settings for SDF II Options data set definition

The members in this data set will contain the overriding or new options. In the translators that you are about to create, you can specify the member that will contain the required options for the particular generate action that relates to the language definition.

Create Rational Team Concert translators and language definitions

A common way to organize the SDF II parts is to have a single BMS map member for the complete map group. Granted, the example here is only a single map in the group, but the setup is the same. So if the DGIPNL is changed, the DGIGRP has to be built. I'll describe how to achieve this a little later. What this means is there will be a single language definition and translator for the DGIGRP.

The translators point to the output types where the generated BMS and copybooks will be created and invokes the SDF II exec described previously.

The first translator to be defined is the translator to build the Panel Group.

Figure 23. SDF II – Panel Group translator
Settings for Panel Group translator

Create a new translator with the following values:

  • Name set to "SDF II – Panel Group"
  • Description set to "Translator for SDF II for CICS/BMS"
  • For Call Method select "TSO Command or Exec" and in the Command/member field enter the location of the BLZSDF2 exec, discussed previously, with the required parameters, discussed below in Table 2. The format of the command is:

    ex 'JAZZ00.RTCZV3.EXEC(BLZSDSF2)' '@{source.dataset} 
    @{source.member.name} G COBOL OPTTYP1'
  • Enter the required DD allocations as described in Table 3
Table 2. Parameters passed to the BLZSDF2 exec
ParameterPurpose
@{source.dataset} Data set name where the source is included from. SDF II uses this to generate a library name by using the prefix.
@{source.member.name} Member name being generated.
G G is set to generate a panel group. If a translator to only generate panels was created, this would be set to P.
COBOL Language type for the generated copybooks.
OPTTYP1 Member name in the data set specified in SDFIIOPT DD. This is an optional parameter and needs to be used only if overriding or additional request options are required.
Table 3. DD allocations for SDF II – panel group translator
AllocationPurpose
DGICOPY This DD sends the generated copybooks to the data set pointed to by the "Copybooks" data set definition. Also set member=yes, because this ensures that the build map is updated correctly.
DGIBMS This DD sends the generated BMS maps to the data set pointed to by the "BMS maps" data set definition. Set member=yes to ensure that the build map is updated correctly.
DGIPNL This DD points to the "DGIPNL" data set definition. This is used to create a relationship between the DGIPNL data set and the DGIGRP data set so that when a DGIPNL is changed, the DGIGRP language definition is invoked. The next section covers the other part of this relationship.
SDFIIOPT This is an optional DD that contains members that specify Request option overrides for particular types of generation. If the defaults in the REXX exec BLZSDF2 are to be used, this DD allocation does not need to be made. If it is made, it will be used in conjunction with the options member passed in the parameters to the BLZSDF2 exec.

Format of request override statements

If a request override DD is used, then the statements must be in the standard SDF-II format. Figure 27 is a sample of the OPTTYP1 member override statements.

Figure 24. SDF II – Format of options file
Screen capture shows SDF II options file contents

The BLZSDF2 exec will match the option name against the defaults specified in the BLZSDF2 exec and override any that have the same name. If there are additional ones in the options member, they will be added to the options used in the generate action.

The second translator to be defined is the BMS map processor translator.

Figure 25. BMS map processing from an SDF II object translator
Settings for BMS Map from SDF II object translator

Create a new translator with the following values:

  • Name set to BMS map processing from SDF II object (object deck generation)
  • Description set to a valid description is required.
  • For Call Method select Called Program and in the Data set definition field select the Assembler data set definition. In the Default options enter SYSPARM(MAP),DECK,NOOBJECT
  • In the DD concatenations select the data set definitions for the CICS SDFHMAC library and the SYS1.MACLIB library, depending on your systems naming conventions.
  • Enter the required DD allocations as described in Table 4
Table 4. DD allocations for BMS Map processing translator
AllocationPurpose
SYSIN Reads the BMS map from the data set and member generator by the previous translator. Notice that member=yes is set.
SYSPUNCH Sends the generated object deck to the temporary object deck data set definition. Set member=no as the temporary object deck is not kept, just passed to the next translator.
SYSPRINT Sends the SYSPRINT output to a temporary file. Notice that Publish=yes so that any output will be published in the build report.
SYSUT1 An assembler work DD that points to a temporary file.
SYSUT2 An assembler work DD that points to a temporary file.
SYSUT3 An assembler work DD that points to a temporary file.

The third translator that is required to be defined is the link-edit translator.

Figure 26. Link-edit translator
Settings for linkage editor translator

Create a new translator with the following values:

  • Name set to Link-edit
  • Description set, if required
  • For Call Method select Called Program and in the Data set definition field select the linkage-editor data set definition. In the Default options enter MAP,RENT,SSI(@{ssi_info}).

    Note:
    The (@{ssi_info} parameter will put the build timestamp into the SSI field in the load module for Rational Team Concert use.
  • In the DD concatenations, select the data set definitions for your Rational Team Concert managed object decks, the CICS SDFHLOAD library and the CEE.SCEELKED library, depending on your systems naming conventions.
  • Enter the required DD allocations as described in Table 5
Table 5. DD allocations for BMS Map processing translator
AllocationPurpose
SYSLIN Reads the generated object deck generator by the previous translator. Notice that member=no is set.
SYSLMOD Sends the generated load module to the data set defined by the program objects data set definition. Set member=yes, because this ensures that the build map is updated correctly.
SYSPRINT Sends the SYSPRINT output to a temporary file. Notice that Publish=yes so that any output will be published in the build report.
SYSUT1 Assembler work DD pointing to a temporary file.

Next you are going to create the Panel Group language definition that invokes all three of the translators you have just defined.

Figure 27. SDF II – Panel Group language definition
Settings for Panel Group language definition

Create a new language definition with the following values:

  • Name set to SDF II – panel Group
  • Language set to Other.
  • For the Translators, use the dialog to Add the three translators you created in the previous steps:
    • SDF II generation of the BMS map and copybook
    • Assemble of the BMS map
    • Link edit of the BMS map

It is also necessary to edit the dependency type's information in the Scanners tab. This is required to allow the build of the DGIGRP when a DGIPNL is edited.

  1. Click the Scanners tab and, in Dependency types, edit the COPY dependency type.
  2. Select the radio button that says Only the translators specified below, and then select the SDF II – Panel Group translator:
Figure 28. Edit Dependency Types in the SDF II language definition
Set dependency type to Panel Group translator

After saving, the Dependency Types list will show the COPY dependency type as only being supported by the SDF II – Panel Group translator, as shown in Figure 29.

Figure 29. Dependency types
Screen shows modified dependency types

Assign languages to parts

When the DGIGRP parts are created, or after they have been shared, they should be assigned the language definition defined above, as Figure 30 shows.

Figure 30. Assigning language definitions to parts
Properties for ORDRSET tab view

If the ISPF Client is used to associate the language definition, use the information option in the member list to bring up the list of available language definitions and select the SDF II – Panel Group language definition that you created.

The DGIPNL parts do not need a language definition assigned to them, because they are associated with the DGIGRP so that if they change, the DGIGRP part is the one that is built.

Associate the DGIPNL with the DGIGRP member

Use the Source Code Data editor in Eclipse to perform this action. At the time of writing this article, it is not possible to modify a parts source code data through the ISPF Client. So, you will have to load the required parts into an Eclipse workspace to make the necessary changes.

  1. In the Eclipse GUI (Figure 31) only, right-click the DGIGRP member, and select Enterprise Extensions > Open Source Code Data Editor.
Figure 31. Opening the source code data editor
Open Source Code data editor to add dependencies
  1. In the source code data editor dialog window, define a data entry for each DGIPNL that is associated with the DGIGRP member.

Note:
Currently, this is the only way to automatically make this connection between the DGIPNL and DGIGRP members. This is because it is impossible to scan the contents of the DGIGRP member on the server to ascertain the dependencies through a custom-written scanner, because the parts are stored in the repository in binary format.

Figure 32. Adding user-defined data for DGIPNL
Associating a DGIPNL member with a DGIGRP member

Build the SDF II objects

To build the SDF II objects, you simply need to ensure your build definition picks up the language definition for the SDF II panel group:

Figure 32. Making sure SDF II language definition is in the build
Adding the SDF II language definition to the build

When the DGIPNL member is edited in the Rational Team Concert ISPF Client and checked-in and delivered a build can now be invoked. Because of the Source Code Data settings you made, the SDF II Panel Group language definition will be invoked and the build done. The build you have set up in this example will generate a copybook and BMS from the SDF II source, then assemble and link-edit the BMS source to create a load module. This is all reflected in the build map for the SDF II panel group, shown in Figure 33.

Figure 33. Build map for DGIGRP member
Build map output showing created parts
Listing 3. Sample output from the build of the SDF II object
<?xml version="1.0"?>
<ISPF-OUTPUT>
 <SERVICE-REQUEST>
<service>TSO</service>
<session>NONE</session>
<command>EXEC 'DOHERTL.RC0TEST.ID94040.EXEC'</command>
 </SERVICE-REQUEST>
 <SERVICE-RESPONSE>
  <TSO>
  <![CDATA[
   ----------------------------------------
   SDF II Generation for member : ORDRSET
   ----------------------------------------
   Prefix         : 'DOHERTL.RC0TEST'
   Type           : G
   Language       : COBOL
   Options member : OPTTYP2
   ----------------------------------------
    
   DGICOPY='DOHERTL.RC0TEST.BMSCOPY'
   DGIBMS ='DOHERTL.RC0TEST.BMS'
   Options data set not allocated
    
   SDF2 request options used
   IIVREQ   = 'G'    /* requests generation              */
   IIVNAM   = 'ORDRSET'
   IIVLIB   = '*'    /* uses search order                */
   IIVTYP   = 'G' /* panel or group etc             */
   IIVMOD   = ''     /* gen for object's target system   */
   ILV10L01 = "'DOHERTL.RC0TEST'"
   ICV10GDS = 'Y'    /* generates a data structure       */
   ICV10GCB = 'Y'    /* generates a control block source */
   ICV10DLA = 'COBOL' /* programming language           */
   ICV10DAL = 'N'    /* gen unaligned data structure     */
   ICV10DGR = 'N'    /* gen no GRAPHIC declarations      */
   ICV10DTR = 'N'    /* gen no TRIGRAPH declarations     */
   ICV10DUE = ''     /* invokes no user exit routine     */
   ICV10DOL = "'DOHERTL.RC0TEST.BMSCOPY'"
   ICV10DOD = ''     /* identifies no ddname             */
   ICV10CDT = '*'    /* gen control block source for all */
   ICV10CUE = ''     /* invokes no user exit routine     */
   ICV10COL = "'DOHERTL.RC0TEST.BMS'"
   ICV10COD = ''     /* identifies no ddname             */
   ISPFIASK = 'Y'    /* Do ISPF allocations              */
   ISPFILVL = '6.1'  /* ISPF Level                       */
   ISPFIPFX = 'ISP'  /* ISPF Prefix                      */
   ISPFILNG = 'EU'   /* ISPF language                    */
   DGIIIPFX = SDF2.V1R4M0  /* SDF2 prefix              */
    
    DOHERTL.RTC.ISPLOG was preallocated (no free was done).
   1SDF II VER 01 REL 04.00                                 2012/06/27    06:47    001

             SSSS   DDDDD   FFFFFF    IIIIII  IIIIII
            SSSSSS  DDDDDD  FFFFFF    IIIIII  IIIIII
            SS      DD   DD FF          II      II
             SS     DD   DD FF          II      II
             SSSS   DD   DD FFFF        II      II
                SS  DD   DD FFFF        II      II
                SS  DD   DD FF          II      II
            SSSSS   DDDDDD  FF        IIIIII  IIIIII
             SSS    DDDDD   FF        IIIIII  IIIIII

   1SDF II VER 01 REL 04.00                                  2012/06/27    06:47    001

    Processing table DGIIFTAB row 00000001
      Type of row . . . . . . . IIVROW  = V
      Type of request . . . . . IIVREQ  = G
      Name of object  . . . . . IIVNAM  = ORDRSET
      Type of object  . . . . . IIVTYP  = G
      Library . . . . . . . . . IIVLIB  = *
      Target System . . . . . . IIVMOD  =

   1SDF II GENERATION                                       2012/06/27    06:47    002
             Object name: ORDRSET type: PANEL GROUP library: 1
             Data Structure
             Output library: 'DOHERTL.RC0TEST.BMSCOPY' member: ORDRSET
    DGICM038 Generation of data structure(s) completed
             CICS/BMS map set for device type 3270
    DGICM021 PANEL ORDRMAP retrieved from library 1
             Output library: 'DOHERTL.RC0TEST.BMS' member: ORDRSET
    DGICM034 Generation of BMS macros completed

    0 Error messages                   3 Informatory messages

   1SDF II VER 01 REL 04.00    Table DGIIFTAB Statistics     2012/06/27    06:47    001

    STEP IIVROW IIVREQ IIVTYP IIVNAM   IIVLIB
    1    V      G      G      ORDRSET  *
    1    Z             G      ORDRSET  1
    1    Z             G      ORDRSET  1
   1      Time       *** ISPF transaction log ***      Userid: DOHERTL
Date: 12/06/27   Page: 1

          06:47   Start of ISPF Log - - -  - Session # 50 -----------------------------
--------------------------
          06:47      TSO     - Command  -  - DGIIX 'DOHERTL.SDF2.REQUEST' 
(EU OFF SDF2INV)
          06:47      TSO     - Command  -  - SDF2INV SDF2I ( EU OFF )
          06:47      TSO     - Command  -  - DGILXLI C
          06:47      Generate ORDRSET G    - Data structure stored in library
'DOHERTL.RC0TEST.BMSCOPY' ( ORDRSET )
          06:47      Generate ORDRSET G    - Control block source stored in library
'DOHERTL.RC0TEST.BMS' ( ORDRSET )
          06:47      TSO     - Command  -  - DGILXLI F
          06:47    End of ISPF Log - - - - - Session # 50 ----------------------------
---------------------------
   JAZZ_TRANSLATOR_RETURN_CODE = 0
  ]]>

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net and try it free on up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=936274
ArticleTitle=Using Screen Definition II with Rational Team Concert
publish-date=07092013