Model 204 installation on IBM z/VSE

Note: This page is currently under construction.

This page describes the steps required to upgrade from Rocket Model 204 version 7.4 to version 7.5, on the IBM z/VSE operating system.

In order to upgrade to Model 204 version 7.5, you must have version 7.4 and the latest Autofix set of Early Warnings installed on your system.

To upgrade to version 7.5 simply download, upload, and link the 7.5 object modules available from the downloads page to install the 7.5 components.

Before you begin

In order to upgrade to version 7.5, you must have version 7.4 and Autofix release EW3044 installed on your system.
Autofix release EW3044 includes:
- Early Warnings for Model 204 through 740EW172
- Early Warnings for Dictionary/204 through 740DI016
For information on Early Warnings, log in to the Rocket Customer Portal.
For system requirements for version 7.5, see the 7.5 Release notes.
You must have either a Rocket M204 user ID or a Sirius user ID to download the installation files.
The sublibrary containing the object has the authorization zap (covering your licensed processors) preapplied, so you do not need to get a new authorization zap from the website.
(The preapplied zap will authorize Model 204 itself and any separately purchased products such as MQ/204 and SirScan.)
The object files also have the maintenance zaps (as of the time the stream was prepared) preapplied, so you do not need to apply any maintenance as part of this installation. (You will only need to apply any new maintenance when it becomes available for this release.)

Overview of upgrading steps

Review the following high-level summary of steps before you begin downloading the Model 204 version 7.5 files.

For an example, see Example workflow for 7.5: download through installation.

Use your Rocket M204 user ID to download the Model 204 object source and JCL, including M204CATP.
Upload (FTP) the downloaded components to the z/VSE system on the IBM mainframe.
Submit the M204CATP job to allocate VSAM managed space for the Model 204 library, define the sublibraries, and catalog the procedures.
If you have your own user $functions (FUNU), you must do the following steps:
1. modify FUNU for 64-bit addressing considerations and store the modified source in your V750 sublibrary.
2. If you have any user-defined messages (MSGU), store them in your V750 sublibrary.
3. Assemble FUNU (and MSGU, if applicable), with the output object file stored in your V750 sublibrary.
If you use an external authorizer (such as RACF) for Model 204, [[assemble the xxxxPARM security module]] (such as RACFPARM). The object file is then stored in your local object library.
If you use other customized modules, such as CDTB, modify them as needed and assemble them.
Link the ONLINE phase.
If you use the IFAM1 phase, link it.
Link the Model 204 utility programs.
If you use the CICS interface, customize it, and then assemble and link the CICS modules.
If you use SoftSpy, upgrade it for 7.5.

CICS interface installation

The Model 204 CICS interface allows CICS complete access to Model 204 facilities and supports CICS pseudo conversational programs.

Note: It is not necessary to install the CICS interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

Requirements

CICS Transaction Server support
Rocket M204 supports the CICS Transaction Server versions 3.1, 3.2, 4.1, and 4.2.
Supporting TPROCESS COBOL applications
If your CICS TPROCESS application was originally linked with AMODE=24, you must relink the CICS TPROCESS application specifying AMODE=31 because AMODE=24 is not supported.

CICS interface overview

For an overview of the CICS interface, including storage requirements and a listing of CICS interface components, see CICS interface.

Installing the CICS interface

Customize the interface by copying the CICFG copy member from RKMACLIB into your local source library and editing it as needed.
For information on customizations needed for using the CICS Standard Mapping Service, see CICS interface.
Update the CICS System Definition (CSD) using one of the following methods:
- Resource Definition Online (CEDA). The supplied member CEDAM204 in RKMACLIB provides an example of the required PCT, PPT, and PLT definitions.
- The IBM DFHSCDUP offline utility, to process the definitions in batch.
Allocate a CICS user library.
Assemble and link the CICS modules.

Updating the CICS System Definition (CSD)

You can update the CSD by using either CEDA or the DFHCSDUP utility and the CEDAM204 member of RKMACLIB. Use the values in the following table, where appropriate, for the method you choose. Information about using CEDA follows the table.

CICS System Definition values

User program	Program name	Transaction ID	Modifiable CICFG symbol	TWA size
IFAM2 pseudo conversational	DFHPSF	DFHPSF is accessed by using a CICS LINK. It is never invoked with a transaction ID from a terminal.
Full-screen interface	M204PSFS	M204	&TRN	88
Screen copy transaction	M204CRPS	U204
Screen print transaction	M204PRNT	P204	&COP	88

CEDA (the Resource Definition Online transaction) or the DFHCSDUP utility defines the transactions and programs to the CSD file.

If you are not using the CEDAM204 member, then define the transactions and programs by using CEDA and the values in the previous table, as in the following example:

CEDA DEFine PROG(program_name) GRoup(group_name) LANGuage(ASSEMBLER) RELoad(NO) RESident(NO) (Except for DFHPSF, RESident(YES)) RSL(PUBLIC) STatus(ENABLED) CEDA DEFine TRANsaction(trans_ID) GRoup(group_name) PROgram(program_name) TWASIZE(twa_size_value) . . . RSL(PUBLIC) . . . CEDA CHeck GRoup(group_name)

You can use a transaction ID for a user program that is different from the value shown in the previous table. However, if you do so, you must change the associated CICFG symbol shown in the table.

As shown in the preceding example, group_name is any valid group name for the user site.

Note: Remember to add the groups to the GRPLIST for the particular CICS region. If the groups are not added, they are not installed during each CICS initialization.

Allocating a CICS user library (JALCICSJ job stream)

One of the members of the RKOBJLIB object library is JALCICSJ, a job stream to allocate an empty CICS user library. You must allocate the CICS user library before assembling and linking the CICS modules.

Copy JALCICSJ into a local TSO library.
Edit your copy of JACICSJ for your configuration:
- Replace the first line with a JOB card.
- Supply your installation high level qualifier(s) in the following lines marked with <<:
  - for hlq in the JCLLIB ORDER=(hlq.... line after the JOB card
  - after HLQ=, on the line after EXEC LKALLUTP at the bottom of the job stream
Submit the JALCICSJ job to allocate the CICS user library.

Assembling and linking CICS modules (LKCICSJ job stream)

One of the members of the RKOBJLIB object library is LKCICSJ, a job stream to assemble and link the Model 204 CICS modules.

Copy LKCICSJ into a local TSO library.
Edit your copy of LKCICSJ for your configuration:
- Replace the first line with a JOB card.
- Supply your Model 204 installation high level qualifier(s) in the following lines marked with <<:
  - for hlq in the JCLLIB ORDER=(hlq.... line after the JOB card
  - after HLQ=, on the line after EXEC JALCICSP at the bottom of the job stream
Submit the LKCICSJ job to assemble and link the CICS module.

Preparing site-specific CDTB, FUNU, and MSGU modules

CDTBASMC, FUNUASMC, and MSGUASMC jobs

If you use translation tables or user-written functions, you must change the source code in the CDTB.A, FUNU.A, and MSGU.A sublibrary members to accommodate the requirements of your site, as shown in the following table.

Customizable user modules

If you use...	Then do this...	Using this job
$CODE and $DECODE functions to encode and decode character strings	Edit your own translation tables into the CDTB.A member	CDTBASMC
Your own User Language functions	Add them to the FUNU.A member	FUNUASMC
Error messages with your own User Language functions	Modify the MSGU.A member	MSGUASMC

The FUNU.A member contains one user function, $SEP, which adds separators when a date is entered in the format mm/dd/yy. MSGU.A also contains one sample error message.

You can use FUNU.A and MSGU.A to write your own user functions. Instructions for coding user functions are in the Model 204 System Manager’s Guide. The steps for installing the modules, as well as assembly considerations, are provided here.

It is recommended that if you think your site will make use of the TCP/IP Sockets Interface for Model 204, link the FUNU.A member during the installation process, even if you have not yet developed your own functions. This ensures access to the $ASCII and $EBCDIC functions.

Assembling CDTB, FUNU, and MSGU

The following table identifies the JCL to assemble CDTB, FUNU, and MSGU and catalog the object decks into the Model 204 sublibrary.

JCL library member for user modules

Member	Assembles and catalogs user modules
CDTBASMC	CDTB (code table)
FUNUASMC	FUNU (functions)
MSGUASMC	MSGU (messages)

Once the modules are assembled and cataloged, link the Model 204 phases to contain user code tables and/or user functions, specifying the M204LIB.Vrrr sublibrary containing the CDTB, FUNU, and MSGU modules in the search list.

The M204LIB.Vrrr sublibrary members LKONLN and LKB204 distributed with this version contain the INCLUDE statements for CDTB, FUNU, and MSGU.

Assembly considerations for FUNU and MSGU

Some of the Model 204 macros and copy code needed to assemble FUNU and MSGU contain assembly language statements that are not supported by the z/VSE assembler. An assembly error occurs in the following circumstances:

EQU statement specifies a length attribute or type attribute. The following example from the VARDEFS copy book illustrates the error:
VISLVL EQU 0,1 FIELD SECURITY LEVEL

The error generated for this statement is:

IPK122 INVALID DELIMITER, ',1'
EQU statement specifies a value that is too long or too large by assembler rules. The following example from the STARTS macro illustrates the error:
MAXFS EQU 16777216/(4096*8) .MAX NUMBER OF INTERNAL FILE SEGMENTS

The error generated for this statement is:

IPK117 VALUE OF SELF-DEFINING TERM '16777216' TOO LARGE

See the z/VSE assembler error message IPK117 for more information.
Symbol defined by an EQU statement of the type described above is referenced in a subsequent assembler statement. The following example from the STARTS macro illustrates the error:
IVBN EQU ((MAXFS+7)/8). MAX # OF BYTES IN SEGMENT BIT PATTERN

Where the error occurs because MAXFS is undefined (see the example in the second bullet, above), the error generated for this statement is:

IPK149 SYMBOL 'MAXFS' NOT PREVIOUSLY DEFINED
In FUNU, some undefined symbols generate the following statement:
QW9 ***** UNDEFINED *****

The error generated for this statement is:

IPK149 SYMBOL 'QW9' NOT PREVIOUSLY DEFINED

The text generated is executable and executes properly (barring logic errors) unless code that references an undefined symbol is executed.

Assembling FUNU and MSGU generates the errors described. However, in FUNU, no assembly errors occur within the FUNUTAB table entries or within the code for a user function (between the $name ENTER statement that begins the function and the LEAVENUM, LEAVESTR, or LEAVEF0 macro that terminates it). In MSGU, no assembly errors occur after the MSGU$ CSECT statement. CDTB receives no assembly errors.

z/VSE assembler errors

Rocket Software takes no responsibility for the errors generated by the z/VSE assembler. It is your responsibility to ensure that you do not code user functions referencing symbols that are undefined due to an assembler error.

Linking the $$BVP204 phase

The following information applies only to z/VSE sites running under z/VM.

The $$BVP204 phase is a transient: it is required for the z/VM-directed output feature, and it is invoked by Model 204 to issue diagnostic instructions in order to pass CP commands to z/VM. $$BVP204 is used to obtain the CPU ID.

Linking $$BVP204 to the system library improves performance.

LINK$BVP SPJCL job

To link $$BVP204, use the LINK$BVP SPJCL job from the JCL library.

This is a required step in a Model 204 installation on z/VSE running under z/VM.

COPYVMPR job

To copy $$BVP204 to the System Residence Library, use the COPYVMPR job from the JCL library.

This is a required step in a Model 204 installation on z/VSE running under z/VM.

Installing terminal access methods and communications features

This section presents basic steps for installing these terminal access methods and communications features:

Model 204 Virtual Telecommunications Access Method (VTAM) Interface.
Horizon intersystem communication feature, which is required for Connect* support. This feature is provided in a limited edition without encryption. See “Installation considerations.”
Parallel Query Option/204, which enables distributed file processing.

General VTAM installation steps

The basic steps for installing these features with Model 204 are:

Link edit Model 204 with the appropriate object modules after commenting out the INCLUDEs for any features (PQO, Horizon, VTAM) not used at your site.
Note: The installation task list for each feature includes this step; however, you need to link edit Model 204 only once, after you apply the CPU ID zap and apply all available Early Warnings.
Complete the Model 204 installation.

Installing the VTAM Interface

Installing Model 204 with VTAM requires defining Model 204 as a VTAM application program. Model 204 provides 3270 support, as well as VTAM support for full-screen terminals that are not 3270-compatible, by providing a mechanism for writing exit routines to convert data outside of the VTAM 3270 interface.

Rules governing data conversion exit routine coding are described in System management. To install the VTAM Interface, perform these steps:

Step	Task	Job
1.	Make sure that the link job contains INCLUDE LKVTAM.	LINKONLN
2.	Define Model 204 as a VTAM application node using an APPL statement in VTMAPPL.B.
3.	Apply all early warnings and then link edit the Model 204 ONLINE phase.	LINKONLN

Specifying a VTAMNAME

The network name of the Model 204 run is specified for VTAM in the Model 204 system parameter VTAMNAME. The VTAMNAME parameter in CCAIN is the same as the APPL statement name field.

The value of VTAMNAME is a string composed of 1-8 characters. The default is M204. VTAMNAME can be specified by the system manager on the User 0 parameter line.

For more information on VTAM parameters, see System management and Commands.

Installing the Horizon Interface

The Horizon intersystem communication feature is required for Connect* and TCP/IP support.

To install the Horizon Interface, perform these steps:

Step	Task	Job
1.	Make sure that the link job contains INCLUDE LKHRZN.	LINKONLN
2.	Apply all early warnings and then link edit the Model 204 ONLINE phase.	LINKONLN

For more information about Horizon, see the Rocket Model 204 Horizon: Intersystem Processing Guide.

Installing Parallel Query Option/204

Parallel Query Option/204 (PQO) enables distributed file processing.

To install PQO, perform these steps:

Step	Task	Job
1.	Make sure that the link job contains INCLUDE LKPQO.	LINKONLN
2.	Apply all early warnings and then link edit the Model 204 ONLINE phase.	LINKONLN

For more information about PQO, see the Parallel Query Option/204 User’s Guide.

Installing CRAM

The Cross-Region Access Method (CRAM) lets two or more Model 204 users in two or more partitions communicate with each other. CRAM is used by:

BATCH2
CICS Interface
IFAM2

See Defining the user environment (CCAIN) for more information about CRAM.

Linking the CRAM phases

To link the CRAM phases (CRAMSWT, CRAMZWT, IGCLM244, and SNAPCRAM), use the LINKCRAM job from the JCL library.