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 installation of previous versions of 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.

The steps for installing Model 204 are:

1. Read the section titled "Important instructions for version m.n", for the version of Model 204 you are installing. This section also contains an example of the complete workflow, from download through completed installation.

   You may wish to consult that example first.

In addition to those version-specific considerations, the following items are performed for every version of Model 204:

2. Download the components for the installation. Be sure to read and heed the note that the object library is not to be modified.
3. Assemble FUNU (and optionally MSGU), if you have user-written $functions; the object file is stored in your local object library.
4. Allocate an authorized Model 204 load library for the version you are installing (in almost all installations).
5. Assemble xxxPARM for your external authorizer if you use one; the object file is stored in your local object library. If you use the dynamic xxxPARM configuration, link xxxPARM into the Model 204 load library.
6. Link the ONLINE (and, if you use them, the IFAM1 and IFAM4) load modules.
7. Link the Model 204 utility load modules.

The above order is recommended, but some variation is possible. The steps starting with "Link the ONLINE" can be performed in any order. The steps prior to that 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" for 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:

• if you have your own user $functions (FUNU),
  • modify FUNU for 64-bit addressing considerations (FUNU must be prepared as the first step during installation
• after you link 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

  • have installed the version V7R1 XDM load modules, and applied early warnings 710EW168 and 710EW199.

  or

  • link the XDM load modules from the downloaded object library

Example workflow: download through installation

This section needs fixing, e.g., for downloading the macro library, and installing CRAM, and ...

This is an example for a site which uses the RACF external authorizer, but otherwise requires no customization, e.g., the site does not use MQ/series nor does it have its own FUNU. The following names are chosen arbitrarily:

• the member name MYBLDOB

and the DSNs

• M204.V75.RKOBJ204.DISTRIB.OBJ
• M204.V75.RKOBJ204.OBJLIB
• M204.V75.LOCAL.OBJLIB
• M204.V75.LOADLIB.

Download; upload; build RKOBJ204

1. Download object file from web site (M204V75.OBJ)
2. Upload to mainframe, Binary, FB/80/6400, as M204.V75.RKOBJ204.DISTRIB.OBJ
3. Create member MYBLDOB by copying the jobstream from "Building the RKOBJ204 object library", using the following at the end of the jobstream:

   //BLDOBJLB EXEC NEWOBJLB, // INP=M204.V75.RKOBJ204.DISTRIB.OBJ // LIB=M204.V75.RKOBJ204.OBJLIB

4. Run MYBLDOB from my TSO library; this deletes and then creates M204.V75.RKOBJ204.OBJLIB

Assemble and link

5. Allocate M204.V75.LOCAL.OBJLIB and copy in:
   • RACFPARM

   Note: We need a step to assemble it - or are we going to sleaze out and not instruct them to assemble a new RACFPARM? In any case this requires downloading the source lib.

6. Allocate M204.V75.LOADLIB and APF authorize it.

   Note: We need info about allocation (simple, just size info) and APF authorization (maybe link to a page discussing it?)

7. Copy member LKONLN2 from M204.V75.RKOBJ204.OBJLIB to my TSO libary, and see all << lines to customize for my site
   • only customization I need is for RACF
   • use M204.V75.LOADLIB as SYSLMOD DD
   • Submit LKONLN2 from my TSO library, this creates ONLINE (and BATCH204 alias) in M204.V75.LOADLIB - I don't need IFAM1 nor IFAM4.
8. Simple smoke test - run BATCH204 with 'DISPLAY ZAPS' and 'ROCKET' commands
9. Copy member LKALLUT2 from M204.V75.RKOBJ204.OBJLIB to my TSO libary, and see all << lines to customize for my site; submit this jobstream
10. Ensure that any JCL which performs deferred index sorting for Model 204 version 7.5 (typically, FLOD jobs) uses the new M204.V75.LOADLIB for the E15 (OI15OS)and E35 (OI35OS) sort exits. This is automatic with standard FLOD JCL.

Reminder: the above section is an example for one typical installation workflow; the remainder of this page explains all installation steps in detail

Downloading the objlib, maclib, and proc files

This is the first step in Model 204 installation.

This section is under construction. It will be cribbed from the instructions on the download page. A key thing mentioned is our use of RKOBJ204 in the documentation to refer to the downloaded object library. Also, emphasize here, in the intro narrative, to not modify RKOBJ204.

Building the object and macro libraries

Once you have uploaded the object and macro library input streams to the mainframe, use the following approach to build the object and macro libraries:

1. Cut and past the following jobstream into your local TSO library: Template:Building RKOBJ204 and RKMAC204
2. On the first line, modify the JOB card according to your local standards.
3. On the final two lines:
   • Modify the INP= parameter, using the DSN of the file you uploaded to the mainframe.
   • Modify the OBJLIB= parameter, choosing the DSN for your Model 204 object library.
   • Modify the MACLIB= parameter, choosing the DSN for your Model 204 macro library.

   You can, of course, dataset names you want — note that in our documentation, we refer to the object library as RKOBJ204 and to the macro library as RKMAC204.

Do not modify RKOBJ204

Once you have built the object library ("RKOBJ204") on your z/OS system, do not update it in any way (unless, in rare circumstances, you download it for the same version of Model 204).

Also, do not store other members into the object library; it should only contain the members as supplied in a download from the web site. For those object files which you might assemble (for example, FUNU or RACFPARM), you should place those into a local object library.

Linking the Model 204 ONLINE load module

This is one of the steps in Model 204 installation.

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 RKOBJ204 is named LKONLN2; it is the ONLINE link jobstream. Copy this into a local TSO library, modify it and submit it to link-edit the Model 204 ONLINE load module.

The items in LKONLN2 (on lines indicated with <<) which can be changed in the copy in your local TSO library are described in the following table.

The comments in LKONLN2 are complete so that you may not need to refer to the instructions below. The LKONLN2 PROC is shown in a sub-section below; it also has a set of instructions, which are more succinct than the instructions in this table.

Note:The following table describes the old approach, which did not contain a JCL PROC. The "succinct instructions" are up to date, and should be used to update this table.

1	One of the modifications 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 RKOBJ204(LKSQLONL) statement. To link an ONLINE which does not use RSQL, you must un-comment the INCLUDE RKOBJ204(LKNOSONL) statement. Do not un-comment both of them.
2	The other modification frequently needed is to use an external authorizer such as RACF or ACF2. If you use and external authorizer, you must: Assemble the xxxPARM for your external authorizer, adding the object file (e.g., RACFPARM or ACF2PARM) to your local object library. In the SYSLIN DD *, un-comment the appropriate INCLUDE statement(s) for your external authorizer. Notes: Uncomment either the "static" or "dynamic" INCLUDE statement, depending upon your configuration. 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, if you have not already done so 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 RKOBJ204.
4	Hence, there are two choices for the RKOBJ204 DD statement: If you have a local object library, fill that in for the first concatenation, and fill in the DSN of the RKOBJ204 library for the second concatenation. If you do not have a local object library, there is only one dataset for the RKOBJ204 DD - your RKOBJ204 library.
5	If you have an MQ series load library, you should un-comment the MQOLIB DD statement, and provide the correct DSN. This allows you to use the MQ Series feature of Model 204, either if you are already authorized for it, or to support a trial of it, without requiring re-linking of the load module.
6	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.

Jobstream to link ONLINE

The downloaded object library contains a member named LKONLN2, which is a jobstream to link the Model 204 ONLINE load module.

1. Copy LKONLN2 into a local TSO library.
2. Edit LKONLN2 for your configuration:
   • Replace the first line with a JOB card.
   • Edit the lines, near the top of the jobstream, marked with 1-6 followed by <<. The numbers correspond to numbered steps in the comments following these lines.
   • As needed, edit the lines after SYSLIN DD * which are marked with <<. See the comments at the top of the SYSLIN sections (A-C) for instructions.
3. Submit the LKONLN2 job to link the ONLINE load module.

The instructions in LKONLN2 should be sufficient to explain the edits you need to make. More expansive instructions are shown in the table above which further explain link-editing the ONLINE load module. Those instructions make use of the numbers (1-6) and letters (A-D) marking lines which need to be edited, or examined for editing.

For your reference, the LKONLN2 member of the downloaded object library contains the following:

//name JOB jobCardParameters //* // JCLLIB ORDER=(hlq.M204V77.RKOBJLIB) required 1 << //* //* For detailed explanations, see //* //* http://m204wiki.rocketsoftware.com/index.php/M204_inst_zOS#lkonln //* //LKONLN EXEC LKM204P, // HLQ=, required 2 << // MQ=ibmMqLoadLibDsn, recommended 3 << // ACF2=acf2SecurityInterfaceLoadOrObjlibDsn optional 4 << //* //* ------------------------------------------------------------------ //* This jobstream is used to link edit the Model 204 ONLINE load //* module. Copy it into a local TSO library, where you will examine //* lines marked '<<' to determine which changes you must make, and //* submit the job with those changes. //* //* There are two groups of changes; those for DSNs (lines 1-4 above) //* and the SYSLIN input. The SYSLIN changes are explained in the //* comments after the SYSLIN DD *. Lines 1-4 are explained here. //* //* Lines 1-2 marked '<<' above MUST be edited and provided; lines 3-4 //* are optional; if they do not apply to your configuration, delete //* them. //* //* 1: Change 'hlq' to the same value provided in (2) - the value //* inside parentheses will then be the DSN of the downloaded //* object library //* //* 2: Provide the high level qualifier(s) of all Model 204 //* installation DSNs //* //* It is recommended that you edit the MQ= paramter line as well: //* //* 3. Provide the DSN system IBM MQ Series load library (and //* uncomment the INCLUDE MQ statement in the SYSLIN input). //* //* The MQ DSN is not required if you will never even trial the //* Model 204 MQ interface. //* //* Delete this line if you are not providing the DSN of the MQ //* load library. //* //* In addition, you might need to provide an additional DSN above: //* //* 4. If you use ACF2 as an external authorizer for Model 204, //* provide the DSN of the system ACF2 load or object library from //* Computer Associates (you will also need to uncomment the //* INCLUDE ACF2 statement in the SYSLIN input). //* //* Delete this line if you do not use ACF2. In that case (to //* avoid a JCL error), remove the comma from the preceding line, //* whether it is HLQ= or MQ=. //* //* ------------ End of description of symbolic parameters ----------- //* //* In addition, you might need to uncomment the BLOCKPRT DD: //* //* 5. If you use block banner separator pages, uncomment the BLOCKPRT //* DD statement and provide the proper DSN (on many systems, this //* is SYS1.AOSB0). //* ------------------------------------------------------------------ //* //* (-- For Rocket Support only: filename=JZJONLN 7.7 2016/11/14 --) //* //*M204LINK.BLOCKPRT DD DISP=SHR,DSN=SYS1.AOSB0 5 << //* //M204LINK.SYSLIN DD * * * Along with the symbolic parameter changes above, see lines marked * '<<' below, make necessary changes, and submit the resulting * jobstream. At the right side of the first line of each section is * a letter followed by some instructions; the letter is used on an * installation wiki page. * * ---- Primary INCLUDE: with or without RSQL --------- Required: A * There are two basic choices for the Model 204 ONLINE load module - * with RSQL (LKSQLONL) or without (LKNOSONL). To choose, uncomment * just one of the next 2 INCLUDEs for this load module: * * INCLUDE RKOBJ204(LKSQLONL) ONLINE with RSQL Uncomment this << * INCLUDE RKOBJ204(LKNOSONL) ONLINE without RSQL or this << * -------- End of primary INCLUDE ------------------------------------ * * ---- INCLUDE for Model 204 MQ interface ------------ Recommended: B * If you uncomment the next line, EXEC LKONLNP must have MQ=dsn: * INCLUDE MQ(CSQBSTUB) To allow use of MQ series << * -------- End of MQ/204 INCLUDE ------------------------------------- * * -------- Security interfaces ----------------------- Optional: C * Ignore from the above line thru and including the "end of security * interfaces" line if you do not use an external authorizer. * * If you use an external authorizer, uncomment the appropriate * line(s) for your interface (if you use ACF2, you will uncomment the * INCLUDE ACF2 line as well as one of the INCLUDE RKOBJ204 lines): * * INCLUDE RKOBJ204(RACFOS,RACFPARM) RACF static RACFPARM << * INCLUDE RKOBJ204(RACFOS) *or* dynamic RACFPARM << * * INCLUDE ACF2($ACFGCVT,ACF$FGCB) ACF2 always needs << * INCLUDE RKOBJ204(ACF2,ACF2PARM) ACF2 static ACF2PARM << * INCLUDE RKOBJ204(ACF2) *or* dynamic ACF2PARM << * * INCLUDE RKOBJ204(TOPSOS,TOPSPARM) Top Secret static TOPSPARM << * INCLUDE RKOBJ204(TOPSOS) *or* dynamic TOPSPARM << * -------- End of security interfaces -------------------------------- * * -------- Block banner separator pages -------------- Optional: D * Ignore from the above line thru and including the "end of block * banner" line if you do not use block banner separator pages. * * If you use block banner separator pages, uncomment the following * INCLUDE statement as well as the corresponding BLOCKPRT DD * statement just before the SYSLIN DD statement above: * * INCLUDE BLOCKPRT(IEFSD095) For block banner separator pages << * -------- End of block banner separator pages ----------------------- * ENTRY MAINTASK ALIAS BATCH204 ALIAS FUNLOAD(FUNLPGM) NAME ONLINE(R) /*

Linking the Model 204 utility load modules

This is one of the steps in Model 204 installation.

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:

1. 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

2. 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.

Jobstream to link utility load modules

The downloaded object library contains a member named LKALLUT2, which is a jobstream to link the Model 204 utility load modules.

1. Copy LKALLUT2 into a local TSO library.
2. Edit LKALLUT2 for your configuration:
   • Replace the first line with a JOB card.
   • Edit the lines marked with << by entering your downloadObjectLib and m204LoadLib dataset names.
3. Submit LKALLUT2 to link the utility load module.

For your reference, the LKALLUT2 member of the downloaded object library contains the following:

//name JOB jobCardParameters //* // JCLLIB ORDER=(hlq.M204V77.RKOBJLIB) 1 << //* //* Jobstream to link Model 204 utility load modules. //* //* In a copy from the downloaded object library, modify all //* lines marked '<<' on the right, and submit the job: //* //* 1: Change 'hlq' to the same value provided in (2) - the value //* inside parentheses will then be the DSN of the downloaded //* object library //* //* 2: Provide the high level qualifier(s) of all Model 204 //* installation DSNs //* //* For detailed explanations, see //* //* http://m204wiki.rocketsoftware.com/index.php/M204_inst_zOS#lkutils //* //* (-- For Rocket Support only: filename=JZJALLUT 7.7 2016/11/14 --) //* //LKALLUT EXEC LKALLUTP, // HLQ= 2 <<

Assembling (and optionally linking) xxxPARM

This is one of the steps in Model 204 installation.

This section is under construction.

Local object library

If you need to assemble a xxxPARM or FUNU module, the output of those assembly step(s) is kept separate from the downloaded object library. To do this, allocate a local object library with the following characteristics:

DCB	LRECL=80 BLKSIZE=6400 RECFM=FB
SPACE	TRK,(100,10,10) — 3390 tracks

FUNU and optional MSGU

This is one of the steps in Model 204 installation.

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

Notes:

• If you have your own FUNU, it must be assembled as before linking the ONLINE/IFAM1/IFAM4 load modules.
• Some customers which have their own FUNU also have their own MSGU module. If so, MSGU must also be assembled before linking ONLINE/IFAM1/IFAM4.

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

1. 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. (This job will also be used to assemble MSGU, if you have it.)
2. Be sure that you have modified the JCL to link ONLINE to reference your local object library (the RKOBJ204 DD statement will be the concatenation of your local object library and the downloaded object library).
3. You do not need to insert any INCLUDE statements for either FUNU nor MSGU; they are already present 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:

FUNU changes for 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.

See also

• Model 204 CMS installation
• Model 204 VSE installation