Developing Applications with Language Environment® and OS/390® - Updated with Strategic Solution Information

In OS/390 Version 2 Release 10, the Language Environment "downward compatibility problem" has been solved.  Specific code changes to this new level of Language Environment and the availability of toleration PTFs for older releases of Language Environment has eliminated the incompatbilities when link editing applications on a higher level of Language Environment and then executing these applications on a lower level of Language Environment. See Downward compatability in Language Environment - Problem solved!, for details on our strategic solution.

For customers who have not upgraded their application development machine to OS/390 Version 2 Release 10, but need to continue application development in the environment they are familiar with while rolling in new releases of OS/390, IBM is providing this Informational APAR as a tactical solution.

Tactical Solution
IBM's tactical solution for the "downward compatibility" issue is to have customers save their older levels of the Language Environment libraries and use them for development. Specifically, customers should maintain their lowest level of Language Environment that is currently active in their production centers' application development machine, and point to these data sets during the assembly, compilation, and link-edit phases of application development.

Note: This solution assumes that you have access to the older releases of Language Environment, including all of the SMP/E data. Customers using a PC Server S/390 (P/390), or R/390 will not be able to use this tactical solution since older levels of Language Environment will not be available on their systems.

Instructions explaining how to save an older level of Language Environment are provided at the end of this APAR.

Example: You have OS/390 R2 propagated in your production centers and are upgrading your test and application development machines to OS/390 R5. In order to implement IBM's tactical solution you should save your Language Environment libraries from your old release (OS/390 R2) onto your test machine and have your application developers point to the respective data sets during development (i.e. use the OS/390 R2 SCEELKED when link-editing your programs). However, for the execution of OS/390 R5 elements and features, you should still use the run-time library from OS/390 R5 (i.e. use the OS/390 R5 SCEERUN in LNKLSTxx or STEPLIB).

This Informational APAR provides a chart differentiating which Language Environment target libraries are used during application development versus which are used during execution. This information should be used to update any JCL, procedures, and TSO/E CLISTs used by your application developers. In addition, specific instructions are provided to allow you to save and maintain older releases of Language Environment regardless of the OS/390 installation method or structure.

Description of Language Environment Target Libraries

The following charts provide a description of the Language Environment target libraries and when they get used. In most cases, the DDDEF entry for the data set is the same as the low-level qualifier (llq). For the cases where this is not true, the appropriate DDDEF entry is listed. The high-level qualifier (hlq) of these data sets may differ from customer to customer, but the default value is CEE. Lastly, the chart is structured to be cumulative, showing when new or changed data sets were introduced.

Legend

Ex - Execution - These data sets get used during execution of an application and must be placed in the program search order.

O - Other - These data sets contain sample jobs, source code, procedures or CLISTs that are not used when assembling, compiling, link-editing or executing programs.

OS/390 V1 Release 1 <=> Language Environment 1.5

OS/390 V1 Release 2

• hlq.MACLIB ==> hlq.SCEEMAC

OS/390 V1 Release 3

• hlq.SCEEUCS2.UCMAP
• hlq.SCEEUCS2.UCONVTBL

OS/390 V2 Release 4

• hlq.SCEELKEX
• hlq.SCEERTLS

OS/390 V2 Release 5

OS/390 V2 Release 6

In this release one new data set will be added:

• hlq.SCEELPA

• hlq.SCEEUCS2.UCMAP ==> hlq.SCEEUMAP
• hlq.SCEEUCS2.UCONVTBL ==> hlq.SCEEUTBL

OS/390 V2 Release 7

No new data sets or changes to names of existing data sets were introduced in this release.

OS/390 V2 Release 8

No new data sets or changes to names of existing data sets were introduced in this release.

OS/390 V2 Release 9

• hlq.SIBMCAL2

Language Environment FMIDs for Different OS/390 Releases

OS/390 V1 Release 1 <=> Language Environment 1.5

HMWL510  -  Base
JMWL51B  -  Base U.S. English
JMWL51D  -  Base Japanese
JMWL51F  -  National Language Resources
JMWL520  -  COBOL Base
JMWL52B  -  COBOL U.S. English
JMWL52D  -  COBOL Japanese
JMWL530  -  PL/I Base
JMWL53B  -  PL/I U.S. English
JMWL53D  -  PL/I Japanese
JMWL540  -  Fortran Base
JMWL54B  -  Fortran U.S. English
JMWL54D  -  Fortran Japanese
JMWL550  -  C/C++ Base
JMWL55B  -  C/C++ U.S. English
JMWL55D  -  C/C++ Japanese
JMWL55F  -  C/C++ Japanese SPC
JMWL55H  -  C/C++ OpenEdition HFS
JMWL55S  -  C/C++ Data Decryption

OS/390 V1 Release 2

HMWL610  -  Base
JMWL61B  -  Base U.S. English
JMWL61D  -  Base Japanese
JMWL61F  -  National Language Resources
JMWL620  -  COBOL Base
JMWL62B  -  COBOL U.S. English
JMWL62D  -  COBOL Japanese
JMWL630  -  PL/I Base
JMWL63B  -  PL/I U.S. English
JMWL63D  -  PL/I Japanese
JMWL640  -  Fortran Base
JMWL64B  -  Fortran U.S. English
JMWL64D  -  Fortran Japanese
JMWL650  -  C/C++ Base
JMWL65B  -  C/C++ U.S. English
JMWL65D  -  C/C++ Japanese
JMWL65F  -  C/C++ Japanese SPC
JMWL65H  -  C/C++ OpenEdition HFS
JMWL65S  -  C/C++ Data Decryption

OS/390 V1 Release 3

HMWL710  -  Base
JMWL71B  -  English
JMWL71D  -  Japanese
JMWL75H  -  HFS
JMWL75S  -  Data Decryption

OS/390 V2 Release 4 <=> OS/390 V2 Release 5

HMWL810  -  Base
JMWL81B  -  English
JMWL81D  -  Japanese
JMWL85H  -  HFS
JMWL85S  -  Data Decryption

OS/390 V2 Release 6

HMWL910  -  Base
JMWL91D  -  Japanese
JMWL95H  -  HFS
JMWL95S  -  Data Decryption

OS/390 V2 Release 7

HLE6607  -  Base
JLE66J7  -  Japanese
JLE66H7  -  HFS
JLE66S7  -  Data Decryption

OS/390 V2 Release 8

HLE6608  -  Base
JLE66J8  -  Japanese
JLE66H8  -  HFS
JLE66S8  -  Data Decryption

OS/390 V2 Release 9

HLE6609  -  Base 
JLE66J9  -  Japanese
JLE66H9  -  HFS

Saving an Older Level of Language Environment

To save an older copy of the Language Environment target libraries, especially the ones used during application development, you can always make a duplicate copy of the target libraries and point to them. This method essentially freezes the service level of the data sets. However, if you want to continue to service the older level of Language Environment, we recommend that you use the SMP/E BUILDMCS command. In the steps below the following terms are used:

FromCSI - The CSI that currently contains the Language Environment information that you want to save

ToCSI - The destination CSI that will contain the older Language Environment information

LEfmids - The list of older Language Environment FMIDs you have installed. If you did not install all of the FMIDs, then your list may be different.

Follow these steps to issue the SMP/E BUILDMCS command:

1. Ensure that the target and distribution zones into which Language Environment is currently installed (the level you want to save in "FromCSI") are at the same service level. This can be determined by running either REPORT SYSMODS or LIST NOACCEPT/LIST NOAPPLY .
    
    

   Example 1: Using the "FromCSI"

   SET BDY(GLOBAL).
     REPORT SYSMODS INZONE(dlbzn) COMPARED TO (tgtzn) NOPUNCH.
   
   

   OR

   Example 2: Using the "FromCSI"

   SET  BDY(tzone).
      LIST NOACCEPT(DLIB).
   
   

2. If any differences are listed in the output, then:
   1. ACCEPT all PTFs and APARs (no USERMODs). When you ACCEPT the differences, you are raising the service level in the distribution libraries. These libraries will be used by BUILDMCS .
       
       

      Example: Using the "FromCSI"

        SET BDY(dzone).
           ACCEPT FORFMID ("LEfmids") PTF APAR.
      
      

   2. RESTORE all USERMODs. When you RESTORE the differences, you are lowering the service level in the target zone.
       
       

      Example: Using the "FromCSI"

        SET BDY(tzone).
           RESTORE S (usermods).
      
      

   Note: Steps 3 - 6 have coding examples. Please click on the step number/ brief description to view the example.
    
3. Create a new CSI (the "ToCSI") since you will require a new global zone. You will not be able to use an existing CSI that has a global zone entry for Language Environment.
    
4. Prime this CSI.
    
5. Allocate separate SMP/E data sets, such as the SMPPTS, SMPLTS, SMPSCDS, SMPSTS, and SMPMTS.
    
6. Define the target and distribution zones, the DSPREFIX, the SREL, and the DDDEF entries for these SMP/E data sets to the "ToCSI".
7. Allocate separate target and distribution libraries for the older Language Environment.

   A sample allocation job called CEEWALOC, found in the older level SCEESAMP data set, can be used to allocate the new libraries. In this job, change the High Level Qualifier (HLQ) variable to something meaningful and identifiable. You may not be able to use the default value of "CEE", since catalog entries may already exist for the the original LE data sets.
    

8. Define SMP/E DDDEFs for the new target and distribution libraries for the older Language Environment (in "ToCSI").
    

   A sample DDDEF job called CEEWDDDF, found in the older level SCEESAMP data set, can be used to define the new libraries. Remember to change the HLQ of the LE target and distribution libraries to match the one used in Step 7. Remember to add a DDDEF entry for the SCEEMAC or MACLIB data set to the distribution zone, if you plan on ACCEPT 'ing any LE USERMODs.
    

9. If you use the OS/390 UNIX System Services (formerly OpenEdition MVS) environment for application development, (i.e. use the c89, cxx, c++, cc utilities to develop production applications) then you will need to create special directories. These directories will contain the C header files that are shipped in the HFS.
    
    

   Customers saving OS/390 Version 2 Release 5 or earlier can use a sample REXX exec called CEEWMKD, found in the older level SCEESAMP data set, to create the new directories.  Customers saving OS/390 Version 2 Release 6 or higher can use a job called CEEISMKD found in the SCEESAMP data set.  Before you execute this exec/job, change the $root variable to high-level directory name other than '/' (root), to prevent installing the older level of the headers under /usr/include.

   Remember to also change the DDDEFs for those directories to include the high-level directory name. This can be accomplished with the SMP/E ZONEEDIT command.

   Example: Using the "ToCSI"

          //*  Please note the replacement string for
             //*  -PathPrefix- is case sensitive and 
             //*  should end in a slash  (/).
             //*
                  SET BDY(tzone).
                    ZONEEDIT DDDEF.
                    CHANGE PATH('/'*, 
                                '-PathPrefix-'*).
                    ENDZONEEDIT.
   
   

10. Run the BUILDMCS against the target zone for the CSI used in Step 1. Ensure that you point the SMPPUNCH data set to a permanent data set to capture the SMP/E image of Language Environment.
     
     

    Example: Using the "FromCSI"

        SET BDY(tzone).
           BUILDMCS FORFMID ("LEfmids").
    
    

    If you get GIM28600W messages during the BUILDMCS process, then you must edit the permanent data set pointed to by the SMPPUNCH DD, and remove the link-edit steps that define these load modules that were mentioned in the GIM28600W message text. You must also remove these load modules from the LMOD parameter of the ++MOD statements. Failure to do so, will cause errors in the APPLY phase of STEP 11.
11. RECEIVE, APPLY and ACCEPT the older "LEfmids". You only need to include the FMIDs that you need for your application development. That is, you may not need to include the HFS FMID, JMWLx5H.
     
     

    Example: Using the "ToCSI" and pointing the SMPPTFIN DD to the SMPPUNCH data set that was generated in Step 10.

               SET BDY(GLOBAL).
                  RECEIVE SYSMODS.
    
                  SET BDY(tzone).
                  APPLY S("LEfmids").
    
                  SET BDY(dzone).
                  ACCEPT S("LEfmids").
    
    

12. RECEIVE and APPLY any USERMODs that you might have RESTORE 'd in Step 2.2.

Conclusion

At this point, you have now successfully created a separate copy of the LE data sets to match your production level, that can be serviced and maintained independent of your OS/390 schedule. To implement this tactical solution, you will need to use the data sets identified above as AD (used during application development), in all your JCL, procedures, and TSO/E CLISTs. You may consider creating catalog alias entries that point to the real data set names, and using these alias names in your JCL, procedures, and TSO/E CLISTs. This method keeps your changes to a minimum when upgrading to a new release, since you would change the catalog alias entry to point to a new level of the data set without having to change your JCL, procedures and TSO/E CLISTs.

OS/390 UNIX System Services Considerations

Besides updating JCL, procedures and TSO/E CLISTs to point to the appropriate data sets of Language Environment some customers may use OS/390 Unix System Services (formerly OpenEdition MVS) as an application development environment. These application developers would use the c89, c++, cxx, cc, utilities to compile and link-edit programs. If your developers are using these utilities and your application development environment is higher than your production environment, then you will need to update the following environment variables:

_INCDIRS - The directories to be used by c89/cc/c++/cxx to search for include files during compilation.

_PLIB_PREFIX - The prefix or HLQ for the LE data sets to be used by c89/cc/c++/cxx.

_PVERSION - The version of the prelinker and runtime to be used by c89/cc/c++/cxx. The values can be:
 

Each environment variable name above is shown with the prefix omitted. To specify cc environment variables, the name shown must be prefixed with _CC (for example, _CC_INCDIRS). To specify c89 environment variables, the name shown must be prefixed with _C89 (for example, _C89_INCDIRS). To specify c++/cxx environment variables, the name shown must be prefixed with _CXX (for example, _CXX_INCDIRS). Please see the UNIX System Services Command Reference for further details on these environment variables.

Scenario

A customer has chosen to implement our tactical solution to save a copy of the OS/390 R3 Language Environment data sets. The HLQ that was used for the Language Environment data sets was SYS1.CEEV1R3 . The directory that was used to save the C headers was /CEEV1R3/usr/include.

This customer would need to update all their JCL, Procedures, and TSO/E CLISTs that refer to the Language Environment AD data sets with SYS1.CEEV1R3 as the high-level qualifier. This customer would also need to update the /etc/profile file with the following statements to enable the c89 utility:

export _C89_INCDIRS="/CEEV1R3/usr/include $_C89_INCDIRS"
export _C89_PLIB_PREFIX="SYS1.CEEV1R3"
export _C89_PVERSION="0x21030000"