5 Installing Oracle GoldenGate for DB2 z/OS Databases
Topics:
- System Services
- Memory Requirements
- Disk Requirements for DB2 z/OS
- Operating System Privileges for DB2 z/OS
- Choosing an Installation Operating System
- Installing Extract Components on Db2 z/OS
- Using Shared Memory Manager for Extract
Parent topic: Installing Oracle GoldenGate for Heterogeneous Databases
System Services
Activate UNIX System Services (USS) only if required to install the executables for the Extract support modules.
Oracle GoldenGate supports Sysplex data sharing.
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Memory Requirements
Oracle GoldenGate requires the following memory resources on the local system.
- On the remote system
-
The amount of memory that is required for Oracle GoldenGate depends on the amount of data being processed, the number of Oracle GoldenGate processes running, the amount of RAM available to Oracle GoldenGate, and the amount of disk space that is available to Oracle GoldenGate for storing pages of RAM temporarily on disk when the operating system needs to free up RAM (typically when a low watermark is reached). This temporary storage of RAM to disk is commonly known as swapping or paging. Depending on the platform, the term swap space can be a swap partition, a swap file, or a shared memory segment (IBM i platforms).
Modern servers have sufficient RAM combined with sufficient swap space and memory management systems to run Oracle GoldenGate. However, increasing the amount of RAM available to Oracle GoldenGate may significantly improve its performance, as well as that of the system in general.
Typical Oracle GoldenGate installations provide RAM in multiples of gigabytes to prevent excessive swapping of RAM pages to disk. The more contention there is for RAM the more swap space that is used.
Excessive swapping to disk causes performance issues for the Extract process in particular, because it must store data from each open transaction until a commit record is received. If Oracle GoldenGate runs on the same system as the database, the amount of RAM that is available becomes critical to the performance of both.
RAM and swap usage are controlled by the operating system, not the Oracle GoldenGate processes. The Oracle GoldenGate cache manager takes advantage of the memory management functions of the operating system to ensure that the Oracle GoldenGate processes work in a sustained and efficient manner. In most cases, users need not change the default Oracle GoldenGate memory management configuration.
For more information about evaluating Oracle GoldenGate memory requirements, see the
CACHEMGR
parameter in the Reference for Oracle GoldenGate. - On the DB2 host system
-
Allocate approximately 10-50 MB of virtual memory for each Oracle GoldenGate log reader,
oggreadx
, that is invoked depending on the size of the log buffer. There is one invocation per Extract process on the remote system. To adjust the maximum log buffer size, use theTRANLOGOPTIONS BUFSIZE
parameter in the Extract parameter file.When setting up the Wotkload Manager (WLM) environment for the Extract log read components, it is recommended to set
NUMTCB
in the range of 10-40 depending on your environment. This is based on the IBM general guidelines available here:
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Disk Requirements for DB2 z/OS
- On the DB2 host system
-
(Only applicable if you are installing stored procedures.) Assign a zFS (zSeries file systems) or hierarchical file system volume. To determine the size of the Oracle GoldenGate download file, examine the size of
zOSPrograms.zip
on the remote DB2 system after extracting the installation image.
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Operating System Privileges for DB2 z/OS
The remote host requires privileges to use the chmod +rw
command on
the sub-directories in the Oracle GoldenGate product directory.
Table 5-1 shows the other required operating system privileges for Oracle GoldenGate:
Table 5-1 Operating System Privileges
DB2 z/OS User Privilege | Extract | Stored Procedures | Replicat |
---|---|---|---|
|
X |
X |
X |
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Choosing an Installation Operating System
Oracle GoldenGate for DB2 for z/OS operates remotely on zLinux, AIX or Intel Linux systems. To capture data, a small component must be installed on the DB2 z/OS system that contains the DB2 instance that will allow Oracle GoldenGate to read the DB2 log data.
To install Oracle GoldenGate on a remote zLinux, AIX or Linux system, you have the following options for connecting to DB2 on the z/OS system:
-
DB2 Connect v10.5 or greater
-
IBM Data Server Driver for ODBC and CLI v10.5 or greater
-
IBM Data Server Client v10.5 or greater
-
IBM Data Server Runtime Client v10.5 or greater
Consider the following:
-
Extract uses Open Database Connectivity (ODBC) to connect to the DB2 subsystem on the z/OS system. If one of the other drivers is not already installed, the IBM Data Server Driver for ODBC and CLI is the most lightweight driver and is recommended for most configurations, although the other drivers are suitable also.
-
To capture DB2 log data, the log reader component must be installed in a Library (PDSE) on the z/OS system. Load Libraries (PDS) are not supported. The library must be authorized program facility (APF) helps your installation protect the system. APF-authorized programs can access system facility (APF) authorized. The log read component is called through SQL from the remote system and since it is APF authorized, an authorized Workload Manager (WLM) environment must also be used to run these programs since the default DB2 supplied WLM environment is not able to run authorized workload.
-
No special requirements beyond what capture already has are necessary for Oracle GoldenGate delivery. Because this Oracle GoldenGate release is a fully-remote distribution, the former Oracle GoldenGate DB2 Remote product is no longer shipped separately. However, Windows is not supported in Oracle GoldenGate for DB2 z/OS in this release. If you still require delivery to z/OS from Windows, then Oracle GoldenGate DB2 Remote 12.2 is still available.
-
UNIX System Services (USS) is no longer required (as in prior releases) except for a few installation procedures.
-
Windows only: To apply data to a DB2 target from Windows, Oracle GoldenGate DB2 Remote v12.2 must be used. Capture is not support in this scenario.
-
Install Oracle GoldenGate DB2 Remote on a remote system for remote delivery to the DB2 target system. In this configuration, Replicat connects to the target DB2 database by using the ODBC API that is supplied in DB2 Connect . This configuration requires DB2 LUW to be installed on the remote system.
Note:
All of the Oracle GoldenGate functionality that is supported for DB2 for z/OS is supported by DB2Connect. In addition, ASCII character data is converted to EBCDIC automatically by DB2 Connect.
-
Although it is possible to install Oracle GoldenGate on zLinux, AIX, and Intel based Linux, the best performance is seen with a system that has the lowest network latency to the z/OS system that you use. Although it is possible to run over a wide area network, the performance suffers due to the increased network latency. Oracle recommends using a zLinux partition on the same physical hardware as the z/OS system that is running DB2 using Hipersockets or a VLAN between the partitions. Otherwise, systems connected with OSA adapters in the same machine room, would be the next best choice. Alternatively, the fastest Ethernet connection between the systems that is available would be acceptable.
Using the Remote Delivery to the DB2 z/OS using DB2Connect
-
For the intermediary system, select any platform that Oracle GoldenGate supports for the DB2 for LUW database. This is the system on which Oracle GoldenGate is installed.
-
Install and run DB2 for LUW on the selected remote system so that the Replicat process can use the supplied DB2 Connect driver.
-
Catalog the DB2 target node in the DB2 for LUW database on the remote system by using the following DB2 command:
catalog tcpip node db2_node_name remote DNS_name server DB2_port-number
-
Add the target DB2 database to the DB2 for LUW catalog on the intermediary system by using the following DB2 command:
catalog db database_name as database_alias at node db_node_name
See the IBM DB2 LUW documentation for more information about these commands.
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Installing Extract Components on Db2 z/OS
-
External programs (authorized) includes the following programs:
-
oggib001
– Initialization and utility program -
oggrb001
– Log read program functionality -
oggmt001
– Stand-alone program that monitors ECSA and 64-bit memory oggjt001
– Setup program for theoggmt001
startup JCL run fromoggib001
program-
oggfr001
– Utility for use by a DBA under guidance from Oracle Support
-
-
SQL stored procedure and function includes
demo_db2_setupb_os390.sql
with theOGGINITB
andOGGREADB SQL
. -
JCL procedure,
oggtask.jcl
Note:
These external names, SQL and JCL names are the default names, which you can edit and update. This process is discussed in the subsequent sections.
The Replication Process for Db2 z/OS Extract figure illustrates the replication process for the Db2 z/OS Extract and its mainframe components.
Figure 5-1 Replication Process for Db2 z/OS Extract
![Replication Process for Db2 z/OS Extract Replication Process for Db2 z/OS Extract](img/db2_zos_installation_components.png)
-
Extract reads the parameters, including the JCL parameters, from the parameter file created during installation.
-
Extract reports the startup information and prepares to write the trail files.
-
ODBC is used to gather information from the Db2 database and start replication.
-
The
OGGINITB
SQL stored procedure starts to prepare shared memory and to gather other data needed for replication. -
The
OGGIB001
external program called by the SQL stored procedure starts the memory monitor task using theOGGJT001
job setup program. -
The
OGGMT001
memory monitor task starts monitoring the ECSA and 64-bit shared memory. -
The
OGGREADB
SQL Function calls the external programOGGRB001
. -
The
OGGRB001
external program repeatedly calls the Db2 log read program to create a result set that returns 1 to many log record buffers to the Extract. -
When a log record result set is complete,
OGGRB001
ends after sending the result set to the Extract.
Extract repeats steps 7 to 9 until shut down or abnormal termination. If
the memory task fails to start, OGGI001
program returns a flag
indicating there was a JCL error or setup issue and Extract manages its own memory.
If the memory task starts properly, the memory task tests constantly changing fields
in the 48-byte ECSA shared memory. These fields stop changing if the Extract
terminates for any reason. At that point, the memory manager waits in case the
Extract or network is slow and releases the memory before shutting down after a
configured time limit.
Note:
The oggifi0001
schema name is configurable using the
TRANLOGOPTIONS REMOTESCHEMA schemaname
parameter.
The procedure names are not configurable. Each of the external names in the
script and the PDSE can be renamed as long as the script names and the PDSE
object names match. Changing these names is part of the procedure that allows
migration to new versions or if specific naming procedures must be adhered to on
Db2 z/OS. The following table contains a check list of components that you may
wish to edit and/or update:
Table 5-2 List of Editable Components
Component | From | Rename | Where |
---|---|---|---|
|
tar file |
authorized PDSE |
|
|
tar file |
authorized PDSE |
|
|
tar file |
authorized PDSE & proc library |
|
|
tar file |
authorized PDSE & Extract parm |
|
|
tar file |
procedure library & Extract parm |
|
proclib |
MVS |
add Extract parm if needed |
|
step libraries |
MVS |
WLM and |
|
remoteschema |
|
||
WLM name |
MVS |
|
|
external program |
|
Note:
Remember to perform all these steps after every new patch installation.
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases
Using Shared Memory Manager for Extract
Oracle GoldenGate Extract starts a separate task, or job, from the WLM to monitor shared memory usage. This memory consists of a small 48 to 64 byte ECSA area, and a large 64-bit area based on the Extract buffer size.
Specific fields in shared memory get updated for every read performed by
the Extract. These fields are updated whether or not the script returns any data.
The monitor checks those fields to ensure the Extract has not become inactive. If
the Extract is inactive, the shared memory is released, and the monitor ends. You
can control the Memory Manager using the remote_memory_options
parameter in the Extract’s parameter file.
You can specify multiple sub-parameters to configure the monitor task. You can configure the wait interval and inactive time the monitor uses by specifying sub-parameters of the remote memory options, as shown in the following example:
remote_memory_options wait_interval 2000 inactive_time 01:00
The wait interval is expressed in hundredths of seconds in the example and causes the monitor to wait 20 seconds between each memory check. If the monitor has checked for 1 hour (format HH:MM) and the Extract is still inactive, then the monitor will shut down after releasing the shared memory. If the Extract returns to an active state during that hour, the monitor will reset its state and continue monitoring.
The wait_interval
can have values from 100 to 6000 and
the default is 1000. The inactive_time
can be from 00:10 to 12:00
and the default is 00:30. If the monitor does not start properly, the Extract
displays a warning message in the Extract report and the Extract continues the
processing. The Extract will attempt to release ECSA memory when it shuts down.
-
task_procedure proc name
-
task_library proc library
-
task_setup task setup program
remote_memory_options task_procedure OGGPR001
remote_memory_options task_library TEST.PROCLIB
remote_memory_options task_setup OGGJT001
You may specify multiple options in a single command, as shown below:
remote_memory_options task_procedure OGGPR001 task_library TEST.PROCLIB task_setup OGGJT001
Note:
The values for the remote memory parameter are case insensitive.The default values are procedure name OGGPR001
and the
task setup program OGGJT001
. There is no default for task library
as the procedure might be installed in one of the MVS system default procedure
libraries. The task library parameter is only needed if the procedure is not in a
system default library.
The memory task will start with a simple JOB card and an
EXEC
procedure name with parameters passed from the Extract.
Some z/OS systems may require various other parameters on the job card. The JOB
parameters can also be modified using the remote memory parameter, as shown in the
example given below.
remote_memory_options task_jobname [valid MVS job name (see below)]
remote_memory_options task_acct_info [valid MVS acct value ( see below)]
remote_memory_options task_programmer [valid MVS programmer name, Can use single quotes]
remote_memory_options task_class [valid MVS job class A to Z or 0 to 9]
remote_memory_options task_msgclass [valid MVS msgclass A to Z or 0 to 9]
remote_memory_options task_msglevel [valid MVS message level n or (,n) or (n,n) n=valid digit]
remote_memory_options task_priority [valid MVS priority 0-15]
You can specify the JOB name using two valid characters and an asterisk,
such as AA*
. The default JOB name is GG*
. The
asterisk is replaced by six random numbers when it is specified. Otherwise, if you
specify a one to eight byte character name, it must be a valid MVS job name.
-
OTXI
-
‘MY ACCT’
-
(ACCT,1234,ABC)
For parameters, like acct_info
and
programmer
, that allow special characters, you must enclose
those in single quotes. In addition, the MVS rules about using double single quotes
or ampersands within quotes continue to apply. The Extract does minimal validation
for these parameters and leaves the complete validation to the MVS process. Extract
will accept the first one if you specify duplicate parameters and ignore any
duplicates.
zOSPrograms.zip
file. The JCL has the following
format://*==================================================================== //* EXAMPLE JCL FOR RUNNING THE COMMON MEMORY MONITOR PROCEDURE //* ADDRESS SPACE NEEDING AN AUTHORIZED LOAD LIBRARY //* NOTE: THE PROGRAM OGGMT001 CAN BE RENAMED IN THE LIBRARY BUT THE //* NEW NAME MUST MATCH THE PROGRAM NAME IN THIS JCL //*==================================================================== //OGGDSNNA PROC RGN=0K TR=,EX=,MEM=,LEN=,SEC=,DUR=,VER= //OGGDSNNX EXEC PGM=OGGMT001,REGION=&RGN,TIME=NOLIMIT, // PARM='&TR &EX &MEM &LEN &SEC &DUR &VER' //*-------------------------------------------------------------------- //* REPLACE &PREFIX.**.AUTHLOAD LIBRARIES WITH SITE SPECIFIC FILE(S) //* ALSO REPLACE THE CEE LIBRARY WITH SITE SPECIFIC FILE //* DSNN COULD REPRESENT A DB2 SPECIFIC LOAD LIBRARY IF ONE EXISTS //*-------------------------------------------------------------------- //STEPLIB DD DISP=SHR,DSN=&PREFIX..WLMDSNN.USER.AUTHLOAD // DD DISP=SHR,DSN=CEE.SCEERUN //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=*
Modify the libraries marked with PREFIX
so that they work in your
system. If you renamed the program OGGMT001
you copied from the
zOSPrograms.tar
file, you must change it in the JCL. The null
parameters on the PROC
statement are there for information
purposes. The job setup program supplies those values using information passed from
the Extract. You may also specify as many step library dataset names as required.
The JCL procedure supplied in the zOSPrograms.tar
file gives an
example using more than one step library.
Parent topic: Installing Oracle GoldenGate for DB2 z/OS Databases