Upgrading to Model 204 version 7.5 on IBM z/OS

This page describes the installation steps for Model 204 on the z/OS operating system. The information applies to installation of Model 204 starting with version 7.5. In substance the information is very similar to installations of previous versions Model 204, but starting with version 7.5, the installation process is new, and self-contained. Therefore,

Do not use the installation process or materials (object files, link edit jobs, documentation, etc.) for previous versions of Model 204 when you are installing version 7.5 or later.

Be sure to read the appropriate section titled "Important instructions for version m.n", for the version of Model 204 you are installing. <div id="always"In addition to those version-specific considerations, the following items must be performed for every version of Model 204:

Assemble FUNU, if you have user-written $functions
Link the ONLINE (and, if you use them, IFAM1 and IFAM4) load modules
Link the Model 204 utility load modules

Step 1 above, assembling FUNU (and, of course, any FUNU considerations for the version of Model 204 being installed), must be performed before linking the ONLINE/IFAM1/IFAM4 load modules. If there are any other ordering requirements in the installation workflow, they will be described in the section titled "Important instructions for version m.n" the version you are installing.

Components for installation

Object library (RKOBJLIB)

The object library is used to link the ONLINE and various other Model 204 load modules.

See the object files download page.

JCL job streams

In addition to the object files, the object library contains a number of z/OS JCL job streams. You will copy each job stream that you need to a local TSO library, modify it according to your system, and submit the job to perform the installation steps.

The job streams in RKOBJLIB all have member names ending in the letter "J."

Macro library (RKMACLIB)

The macro library is used if your installation requires assembling of any ASSEMBLE files.

RKMACLIB contains:

Model 204 macros
Sample files for: FUNU, MSGU, RACFPARM, ACF2PARM, TOPSPARM, TSFS, ZFIELD proc

See the macro libraries download page.

Important instructions for version 7.5

In addition to the steps performed for every version, installation of version 7.5 requires that you:

after linking the utility load modules|, be sure to use your version 7.5 load library for the OI15OS and OI35OS load modules used in the deferred index sort exits for FLOD
if you use XDM CRAM, either:
- have installed the version V7R4 XDM load modules
or
- link the XDM load modules from the downloaded object library
if you have your own user $functions (FUNU),
- modify FUNU for 64-bit addressing considerations

Downloading the object library

This section is under construction. It will be cribbed from the instructions on the download page. A key thing mentioned is our use of ROKOB204 in the documentation to refer to the downloaded object library.

Linking the Model 204 ONLINE load module

Note: If you have your own FUNU, it must be assembled before linking the ONLINE/IFAM1/IFAM4 load modules.

After downloading the object library, one of the members of ROKOB204 is named JZLONLN - the basic ONLINE link JCL. You can use this to link-edit the Model 204 online. It contains a number of choices which you can make to modify this basic JCL; each choice is indicated in the JCL by a line which ends with <<.

Most of the choices are "optional", in the sense that a working ONLINE does not require the indicated modification, although, for many customers' environments, a modification will be needed, for example, to select an external authorizer.

1	Only one modification is always required, based on whether the ONLINE is to use RSQL (for Connect) or not: To link an ONLINE which does* use RSQL, you must un-comment the INCLUDE ROKOB204(LKSQLONL) statement. To link an ONLINE which does not use RSQL, you must un-comment the INCLUDE ROKOB204(LKNOSONL) statement.
2	The other modification frequently needed is to use an external authorizer such as RACF or ACF2. If you do, you must: Prepare the appropriate xxxPARM object file (e.g., RACFPARM or ACF2PARM), adding that to a different object library (with the same DCB attributes as ROKOB204). We refer to this as your local object library (it will also be used for other assemble output, such as your FUNU). In the SYSLIN DD , un-comment the appropriate INCLUDE statement(s) for your external authorizer. Note:* If you use ACF2, there are two INCLUDE statements to be un-commented; one refers to your system ACF2 library. You must un-comment the ACF2 DD as well, and fill in the DSN for that library.
3	If you have other programs which you assemble for your Model 204 ONLINE module, for example, FUNU, they should be assembled into your local object library (creating one - with the same DCB attributes as ROKOB204 - if you have not already created one for the external authorizer xxxxPARM object file). You do not need to add additional INCLUDE statements for FUNU or other locally assembled object files - they are already present in the include streams from ROKOB204.
4	Hence, there are two choices for the ROKOB204 DD statement: If you have a local object library, fill that in for the first concatenation, and fill in the ROKOB204 DSN for the second concatenation. If you do not have a local object library, there is only one dataset for the ROKOB204 DD - your ROKOB204 library.
5	Finally, change the DSN of the SYSLMOD DD to the load module library you have allocated for it.

The modified JCL is now ready to run.

Notes:

There is not a separate link step for BATCH204. It is not maintained as a separate module; the same module as ONLINE is used, with a BATCH204 alias.
The object library has the authorization zap pre-applied, so you *do not* need to get a new one from the web site.
It also has the maintenance zaps (as of the time the stream was prepared) pre-applied, so you *do not* need to apply any maintenance.

Basic JCL to link ONLINE

//LKM204P PROC HLQ=, High level qualifier(s) of install DSNs // MQ=NULLFILE, IBM MQ series load library // ACF2=NULLFILE ACF2 security interface load/objlib //* //* ******* z/OS JCL PROC to link edit into Model 204 loadlib ****** //* //* ****************************************************************** //* ** Do not copy nor edit this PROC. It is invoked by a ** //* ** jobstream member (such as LKONLNJ, LKIFAM1, etc.) for the ** //* ** particular load module you are linking. You should copy the ** //* ** jobstream member from the downloaded object library and then ** //* ** edit in a local TSO library. The jobstream contains ** //* ** instructions to modify and submit that jobstream. ** //* ****************************************************************** //* //* The first symbolic parameter (HLQ=) is required. //* //* The other two depend on the jobstream being used to invoke this //* PROC, and on your Model 204 configuration. //* //* Detailed explanations are also available for the load module //* you are linking at //* //* http://m204wiki.rocketsoftware.com/index.php/M204_inst_zOS //* //M204LINK EXEC PGM=IEWL,REGION=0M, // PARM='SIZE=(2048K,200K),LIST,LET,NCAL,MAP,AC=1,RMODE=ANY' //SYSPRINT DD SYSOUT=* //* //RKOBJ204 DD DISP=SHR,DSN=&HLQ..M204V75.LOCAL.OBJLIB, // DCB=BLKSIZE=32720 // DD DISP=SHR,DSN=&HLQ..M204V75.RKOBJLIB Downloaded obj lib //* //SYSLMOD DD DISP=SHR,DSN=&HLQ..M204V75.LOADLIB Model 204 modules //* //MQ DD DISP=SHR,DSN=&MQ IBM MQ series load library //* //ACF2 DD DISP=SHR,DSN=&ACF2 ACF2 system load/object library //* // PEND ************** End of LKM204P PROC *************

Linking the Model 204 utility load modules

This section describes how to link edit the Model 204 utilities. This step must be performed whenever installing a new version of Model 204.

Many of the utility load modules are compatible across versions of Model 204; therefore, your z/OS jobs which use older versions of those load modules will continue to perform correctly when used in conjunction with the new version of Model 204, and you do not need to change the JOBLIB nor STEPLIB JCL — for example, you do not need to change any of your batch jobs which have PGM=BATCH204.

However, for some utility load modules, you must use the new version. These modules are:

A few utilities are sensitive to the Model 204 journal and checkpoint format. Therefore, when you are using the following utilities, you must use the version of the utility which is the same as the version of the checkpoint or journal dataset it processes:

AUDIT204 Extract from journal, and report stats and analysis

MERGEJ Merge concurrent journal streams

UTILC Information from checkpoint stream

UTILJ Information from journal stream; add EOF markers

and

In addition to the above utility load modules, be sure to read the sub-section titled "Important instructions for version m.n", for the version of Model 204 you are installing; it may contain instructions for other utility load modules for which you must use a new version.

The downloaded object library contains a member, named LKLALLUT, which is a JCL PROC to link the Model 204 utility load modules. This PROC is invoked as follows; place your downloadObjectLib and m204LoadLib dataset names on the three lines indicated with <<:

//name JOB jobCardParameters // JCLLIB ORDER=(downloadObjectLib) << //LKALLUT EXEC LKALLUT, // ROKOB204=downloadObjectLib, << // SYSLMOD=m204LoadLib <<

The exact contents of LKLALLUT in the object library will depend on the version of Model 204 being installed — you do not need to modify it. A prototype copy of it is shown here; the download process provides the proper concatenation of ROKOB204 members for the SYSLIN DD:

Template:JZLALLUT

FUNU

This section lists installation considerations if you have your own user-written $functions module (FUNU). These instructions apply to every installation of Model 204.

Note: If you have your own FUNU, it must be assembled as before linking the ONLINE/IFAM1/IFAM4 load modules.

If you have your own FUNU, the following items are required for installation of every version of Model 204:

After making any changes required for the version of Model 204 you are installing, run the job to assemble FUNU into your local object library.
Be sure that you have modified the JCL to link ONLINE to reference your local object library (the ROKOB204 DD statement will be the concatenation of your local object library and the downloaded object library).
You do not need to insert an INCLUDE statement for FUNU; there is already one in the INCLUDE member (LKSQLONL or LKNOSONL) provided in the downloaded object library.

In addition, see additional FUNU considerations as described in the following sections:

Versions 7.5 and later

Starting with version 7.5 of Model 204, all $functions are entered in AMODE 64. This requires you to modify the ENTER macro for each $function, and may require you to modify the code for proper addressing in AMODE 64.

In order to exploit QTBL above the 2G bar, any $functions which has arguments must be in AMODE 64. The ENTER macro should use ZMODE=GQ (the AMODE will remain as 64) and the code must be changed for proper addressing.
For the ENTER macro, the ZMODE operand default value (for FUNU only) is ZMODE=31. So if the $function does not have any arguments or if you will not exploit QTBL above the bar, and if the $function does not access any data structures above the bar, either specify ZMODE=31 or omit the ZMODE operand. (Note that most Model 204 data structures can be above the bar, including $function arguments.) The ZMODE=31 value will be used, causing your $function to switch to AMODE 31 at entry (and restore the AMODE upon exit).
In any case, the AMODE issues need to be accounted for in any routines which your $function routine does a CCALL to.