Perform an Online Area Move for Index and Data Areas

Product: CA Datacom®/DB
datacom151
 
Product: CA Datacom®/DB
 
 
Release: 15.1
 
 
OS: z/OS
 
The Online Area Move (OAM) functionality provides support for 24x7 businesses. Using the Multi-User Facility (MUF), you can move index and data areas from one physical data set to another without interrupting user access to the data rows and indices that are stored in those areas.
This scenario describes how a database administrator (DBA) or a system programmer prepares for the OAM process to move an index or data area from one physical 3390 data set to another 3390 data set.
The OAM functionality allows you to move CA Datacom data sets to support your business needs without causing data access outages to your users.
Examples of the business needs that you might encounter are:
Data sets are on older 3390 models that no longer provide adequate allocation sizes. For example, a 3390 Mod 3.
Data sets are not on 3390 models that are available at your selected Disaster Recovery (DR) site which restricts your ability to move all of your data efficiently to the DR site.
Data sets were sized for initial expected amounts of data. The data volume has grown significantly and the data set is now reaching maximum allowable extents.
This Knowledge Base Article constitutes a portion of the official CA product documentation for this CA product. This Knowledge Base Article is subject to the following notices, terms and conditions.
The following topics are discussed on this page:
 
 
Performing an Online Area Move
OAM provides a powerful tool for the dba or systems programmer in an installation where user data must remain available and accessible 24x7. You can initiate OAM using one of the following methods:
  • Issue a console command to the MUF.
  • Execute a batch DBUTLTY job utilizing the OPTION=CONSOLE function.
  • Insert a new row into the SQL_CONSOLE dynamic systems table.
 Three additional DBUTLTY functions relating to the successful use of the OAM are documented in Preparing for an Online Area Move.
  • The DBUTLTY PREINIT function prepares (initializes) a new data set (target area) to be the output to the OAM.
  • The DBUTLTY REPORT AREA=CXX,TYPE=P lists data sets that PREINIT sets up.
  • The DBUTLY CXXMAINT OPTION=DPREINIT function removes any unneeded PREINIT data sets.
 
Benefits
 
Some of the benefits include:
  • Moves physical data sets without causing an interruption to user data access.
  • Dynamic movement of area data sets to support 3390 model upgrades, new DASD devices, and so on.
  • Provides an outage-free method for you to move/reallocate a data set that is nearing volume or extent maximums.
Complete the following steps to perform an Online Area Move:
Determine an Online Area Move is needed
Depending on the circumstances, you may only need to use the OAM process for a few data sets over a significant period of time. Then a certain project comes up, new hardware is installed, or data volume suddenly grows and you are faced with the need to implement OAM immediately for several data sets or even in some cases entire environments.
One special case for which the OAM feature could be useful would be the following:
You have an area that was sized according to known data patterns and has been functioning normally. Suddenly a large volume of new data hits the area. The automatic extend process handles the dramatic data growth. However, now the area is at or near the z/OS limitations of 16 extents on all available volumes (or the z/OS maximum of 59). At this point, you can use OAM to build a target data set with larger extents. With OAM, a new larger data set can be created and the near-maximum situation is handled without causing a data access interruption.
Once OAM is started, even a data set that is full and has reached the “maximum allowable” extents can still be used for data additions. After an OAM starts, all new block usage occurs in the new target area with the space allocation set in the PREINIT. If that space is not enough to support the new additional data, a dynamic extend of the new target area occurs and makes room for the new data. This capability allows OAM to move a full area (that cannot be closed) to a larger data set extent and, at the same time, allow the addition of new data.
Because an OAM can execute for long periods of time, we strongly recommend that you review the best practices and limitations/restrictions each time you prepare for an OAM. This information can help avoid circumstances where the OAM process conflicts with other processes in your systems.
Review limitations and restrictions
Follow the limitation and restrictions to complete the OAM process successfully. Any deviation or violation of these restrictions can cause the OAM to fail.
Online Area Move cannot be used in a full data sharing environment (MUFPLEX)
 
Important! 
OAM is 
not
 supported when running in a full data sharing environment. A full data sharing environment means that there are two MUFs actively processing the same databases as a MUFPLEX.
OAM is supported in a Shadow MUFPLEX environment where there is one MUF running active and one MUF in SHADOW mode.
Do not start the OAM process if:
  • The MUF is currently part of an active data sharing MUFPLEX
  • There are plans to activate the Shadow MUF into an active data sharing member with the MIGRATE command
For more information, see MUFPLEX and Shadow MUFPLEX
Online Area Move and the MUFPLEX
Since OAM executes within the confines of a single MUF address space, the OAM process cannot be started in a MUF that is running in an active data sharing mode where two MUFs are sharing data across the SYSPLEX Coupling Facility.
Examples are:
  • MUFPLEX MODE=A with two or more active data sharing members (MUFs)
  • MUFPLEX MODE=B with two or more active data sharing members (MUFs)
  • MUFPLEX MODE=S (Shadow) when the Shadow MUF has been activated using the MIGRATE command
Sites using MUFPLEX should not use OAM unless they can execute the OAM utility to full completion during a time when only one of the member MUFs is executing.
If the need arises to active data sharing, an OAM can be stopped by closing the database containing the area and the database can be left closed and the OAM restarted after the need for active data sharing has passed. This situation is avoided by ensuring that moves can be fully completed when only a single MUF is enabled. Fully complete includes having:
  • All blocks are moved
  • Old area is renamed or deleted
  • New area is renamed
If an OAM process is running (not complete) the activation of an active data sharing environment is blocked until the OAM process completes or the area being moved is closed (forcing the OAM to stop processing).
If a database CLOSE request stops an OAM process, the activation of an active data sharing environment is allowed. However, the area in question is not permitted to OPEN while the environment is running in the active data sharing mode.
MUF must have RENAME and SCRATCH authority
The OAM process runs inside of MUF as an internal task. Therefore, it is the MUF that requests the z/OS data set renames and optionally deletes of the source data set after the move has completed.
The security ID associated with the MUF region must have authority (security) to issue the data set renames and optionally data set deletes.
This is the first time that RENAME and DELETE (SCRATCH) authority has been required for the MUF region.
 
Important!
 Before attempting to use the OAM process, ensure that the submitter ID of the MUF region has the appropriate authority as noted previously.
MUF must have available task or request areas
Each OAM process requires one user-defined TASK (REQUEST AREA) within the MUF. User-defined TASKS are allocated at MUF startup using the TASKS= parameter.
You can determine if the MUF targeted for OAM process has available TASKS. Simply run a DBUTLTY COMM=STATUS command or a dynamic systems table query against the SYSADM.MUF_TASKS table.
If no tasks are available, the OAM does not start. If the OAM does start and it runs for a long time, it holds onto the task area until the process completes or it is forced to stop. If the MUF is running short of available tasks, the OAM can tie up a task that is required to process necessary user work.
MUF must have available 24-bit memory
Each OAM process requires the MUF to open the target data set in addition to the existing source area. This task is accomplished by using a generated DD card for the target data set.
Each data set opened by MUF requires a certain amount of 24-bit memory. The amount of required memory varies per data set depending on the number of volumes and extents that the data set uses.
In version 14.0, the 24-bit memory that the source and target data sets use remains “in-use” within the MUF until the MUF is recycled. During the recycle, the new MUF instance only opens the new data set (target). Therefore, the previously required 24-bit storage for the old data set (source) is no longer allocated. A failover or migration to the Shadow MUF also opens only the target data sets for completed OAMs.
You can determine if the MUF targeted for OAM process has available 24-bit storage by using one of the available system management tools. These tools can determine the amount of private (24 bit) storage available in the region and how much is used currently.
Take this measurement after the MUF has been initiated and all normal user databases and their underlying data sets have been opened for processing.
 
Important! If the MUF address space runs out of 24-bit storage, the address space could fail causing a significant interruption to all user access.
 
Using CA Sysview to display available 24 bit memory in the MUF address space
Select the MUF address space from the Sysview command screen. For example, you can make this selection in the following ways:
ASID QA14MUF4 (where QA14MUF4 is the MUF JOB NAME).
Enter the CA Sysview command PRIVATE to display available storage after you select the MUF address space as shown in the following example:
SYSVIEW ISPF2 CA31 ------------------------- PRIVATE.SUMMARY, Private Storage Sum Command ====> PRIVATE ---------------------------------------------------------------------------------
Jobname QA14MUF4 ASID 0071 Jobid JOB05085 Region Size UnAlloc/Large Alloc/Pct% Used/Pct% Free HWM/Pct% Limit E-PVT 1.09G 972M 972M 141M 13% 140M 13% 376K 141M 13% E-SYS 982M 972M 972M 10.1M 1% 9.97M 1% 223K 10.3M 1% E-USR 1.08G 972M 972M 131M 12% 131M 12% 153K 131M 12% 1.09G PVT 7.98M 7.41M 7.39M 592K 7% 436K 5% 155K 824K 10% SYS 7.77M 7.39M 7.39M 388K 5% 266K 3% 121K 612K 8% USR
7.59M 7.39M 7.39M 204K 3% 169K 2% 34K 212K 3% 7.98M
<=========
--------------------------------------------------------------------------------- Cmd Type Spn Key 0 1 2 3 4 5 6 7 8 9-15 Total ___ USR 0 122M 122M ___ USR 131 75K 75K ___ USR 132 6.52K 6.52K ___ LSQA 205 905K 905K ___ LSQA 215 121K 121K ___ LSQA 225 3.63K 3.63K ___ AUK 229 596K 301K 296 204K 4K 1.08M ___ AUK 230 231K 351K 4.65K 23.5K 27.5K 173K 4.65K 4.65K 129K 4.65K 955K ___ SWA 236 169K 169K ___ SWA 237 517K 517K
The line indicated by the arrow in the display shows the available user 24-bit storage. In this case, there is 7.59M of space with the current use at 481K (6%) and the high water mark used (HWM) at 520K (7%). This MUF has plenty of available space for more data sets to open by the OAM process.
If the MUF in question has a significant portion of the 24-bit (PVT USR) in use or listed in HWM (60-70%), you should limit the number of OAM processes executed.
After completing one or more of the OAM processes, recheck the 24-bit storage ensuring that the available storage continues to be reasonable after the completed OAM processes.
Criteria for source and target data areas
The following OAM criteria must be met:
  • MUF must be up with full access to the source data area.
  • Data area source/target data sets must be defined on a 3390 device.
  • Target data set should be defined as large as (or larger than) the source data set.
  • Source/Target data set should have dynamic extend enabled to allow for data area growth as needed during the OAM process.
  • Data area must be defined as URI.
  • Data area must be part of a buffer pool that holds at least 120K of data. For example: 30 4K buffers.
  • Data areas that are used to support a partitioned table are treated as individual data areas. As such, each can be subject to an OAM as needed without concern for the other data areas used by this partitioned table.
Criteria for source and target index areas
The following OAM criteria must be met:
  • MUF must be up with full access to the source index area.
  • Index area source/target data sets must be defined on a 3390 device.
  • Target data set should be defined as large (or larger) than the source data set.
  • Source/Target data set should have dynamic extend enabled to allow for data area growth as needed during the OAM process.
  • Index area must be part of a buffer pool that holds at least 120 K of data. For example: 30 (4K) buffers.
  • Index areas that are used as part of a multi-data set index are treated as individual index areas. As such, each can be subject to an OAM as needed without concern for the other index areas used by the multi-data set index.
  • Multi-data set index areas must be moved using the same source/target index area names -- meaning ONLINE_AREA_MOVE must be IXX to IXX, I01 to I01, and so on.
No single user access
Once an OAM is started for a data set, the associated index or data area is not available for any single-user processes.
For most sites, this restriction affects the use of DBUTLTY functions such as BACKUP, LOAD, and RETIX (without KEYNAME=). The only DBUTLTY functions that can execute against the index or data areas that are involved in an active OAM are those DBUTLTY functions that are executing through the MUF and do not conflict with the OAM process.
 
Example
 
OLREORG and DEFRAG are processes that can execute against a data table (OLREORG) or an Index Area (DEFRAG) while an OAM process is executing.
This restriction is also in effect for areas that have an OAM process that has been interrupted. For more information about the ways that the OAM process can be interrupted, see Interruption and re-initiation of the Online Are aMove Processes. 
 
Important!
 OAM must be allowed to complete as quickly as possible. Having an OAM in an interrupted state may mean that regularly scheduled DBUTLTY processes such as a nightly backup can fail.
Backing up data sets during an OAM
 
Important!
 Do not use non-Datacom tools to back up data sets during an OAM. The OAM must be allowed to complete as quickly as possible. Having an OAM in process while a non-Datacom backup is taken could result in an unusable backup.
Many sites use non-Datacom utilities to create physical backups of the CA Datacom data sets. These utilities create a physical copy of the data sets regardless of the processes going on within MUF.
In most cases, these utilities process using selected data set names or high-level qualifiers. Additionally, the utilities normally process through a segment of DASD in a serial fashion.
Because the OAM process is using two data sets that are probably on different DASD volumes or even different DASD devices, the ability to capture the source and target data sets “in-synch” is unlikely. The non-Datacom backup process completes without error but the captured data is most likely out of sync. A future attempt to restore the data sets from the backup can result in missing or out of sync data.
The only way to create a non-Datacom backup would be to ensure that the OAM process had been QUIESCED before taking the backup. For more information, see QUIESCE.
Review Best Practices
Best practices differ from restrictions and limitation because they are suggestions to achieve the best result. Limitations and Restrictions provide information to keep the OAM process from failing.
The following best practices are recommended to ensure that the OAM process completes in the most efficient and beneficial manner.
Ensure task and 24-bit memory availability in the MUF
Always check the availability of tasks and 24-bit memory before starting the OAM process.
 
More information:
 
Available task request areas 
Available 24-bit memory 
Avoid hard-coding of CA Datacom data sets (DD CARDS)
There are only a few DBUTLTY data set initialization tasks where the DD card must be included in the executing JCL providing the data set name. Tasks executing against the MUF and MUF itself do not need the DD cards to be included in their execution JCL. The required data sets are dynamically allocated using the data set information that is stored in the CXX. The same is true for the DBUTLTY executions where the data sets are already known from a previous DBUTLTY INIT process.
Avoid hard coding any CA Datacom data set (DD card) in JCL job streams to avoid any possible conflict with the OAM rename/scratch process. Having a job executing with a hard-coded DD card could interfere with the OAM ability to rename/scratch the old (source) data set which could leave the OAM process in an in-complete state.
For more information about exception handling and why area (data sets) being moved cannot be renamed or deleted, see Complete the OAM.
Update source area dynamic extend attributes before PREINIT
The PREINIT data set is created using the information for the source area in the CXX. Therefore, we recommend that you update all source definitions to support dynamic extend before the PREINIT execution.
Define both the source and target (PREINIT) data sets with DYNAMIC EXTEND attributes to:
  • Ensure that OAM can continue to process
  • Successfully handle data growth (user adding new rows) that can occur after the OAM is started
 
Important!
 You can use CA Datacom Datadictionary processes to change DYNAMIC EXTEND attributes. For the change to take effect, DYNAMIC EXTEND attributes must be updated to the CXX. To update the CXX without requiring the database to be closed to MUF, use the Datadictionary "-1000 ALTER" command.
Create the PREINIT data sets
Create the PREINIT data sets in advance of the execution of the OAM. As a best practice, ensure that the creation of the PREINIT data set is done close to the execution of the OAM. Creating the data set far in advance of the OAM may mean that the PREINIT data set is not sized correctly to handle the data that is present when the OAM is executed.
Size the PREINIT data set such that its initial extent is large enough to handle the current data requirements plus any near term data growth. The PREINIT "Volume=" parameter can be used to help size the data set area if your data set needs to span multiple volumes.
Using this philosophy you:
  • Ensure that the minimum number of volumes and extents are created. This task limits the amount of 24-bit storage that is used to manage the target dataset once the OAM starts.
  • Ensure that the OAM process is not delayed while the target data set is being extended to a size large enough to handle the source data.
  • Ensure that the maximum number of additional volumes and extents are available for future processing growth.
Processes to avoid while ONLINE AREA MOVE is active
Avoid using any DBUTLTY functions for the area while OAM is processing. Not using DBUTLTY processes avoids resource contentions that could lead to slow response time for user tasks that are accessing the data and longer execution times for the OAM process.
Single-user (DBUTLTY) functions that process the area outside of the MUF are not permitted to execute while the OAM is active. In addition, non-Datacom processes such as DASD backups should not be attempted while the OAM is active. For more information, see Limitations and Restrictions.
However, there are various processes that run in MUF and are supported for execution while the OAM is active, but should still be avoided. Avoiding these processes, allows OAM to complete in the fastest time possible with the least amount of conflict.
Avoid the following DBUTLTY functions as they are very IO intensive and while they operate, they may slow down the OAM process.
  • OLREORG
  • DEFRAG
  • DATASCAN OPTION=REBUILD_SPACE_INDEX (RETIX KEYNAME=*DATA) or KEYNAME=*SETR
  • MASSADD
  • REPLACE
  • BACKUP SEQ=PHYSICAL with MULTUSE=YES
  • Periods where there is heavy user updating (add, delete, update).
 Heavy user updating is supported, but can slow the OAM process. Having large buffer pools or covered data can help mitigate this concern.
Ensure MUF has a reasonable number of buffers
A minimum amount of MUF buffering is required for OAM processing (120K). Having a more substantial buffer pool allows the OAM process to function faster while the MUF is also supporting various user processing requests.
For more information, see Review limitations and restrictions.
Avoid starting an OAM if the process may be interrupted due to a system or MUF process
Certain events/processes interrupt the OAM process. For more information, see Limitations and Restrictions. Do not start the OAM if any planned system or other activity can affect it, such as:
  • IPL
  • Activating a SHADOW MIGRATE (All blocks must have been moved and the area delete/rename process completed before this occurs.)
  • Starting a second Data sharing member (MODE A or B) (All blocks must have been moved and the area delete/rename process completed before this occurs.)
  • Attempts to run DBUTLTY single user jobs like BACKUP MULTUSE=NO
  • Avoid the QUIESCE periods if possible
  • If you are using a non-Datacom backup:
    • Always ensure that the source and target data sets are part of the same backup group.
    • Always ensure that the source and targets are backed up at the same consistency point.
    • If OAM is not quiesced, do not use a non-Datacom utility to back up data sets.
Starting the process
After you review the limitations/restrictions and best practices, you are now ready to start the OAM process.
Create the PREINIT data sets
To create the target data sets, follow the steps in How to Prepare for an Online Area Move for Index and Data Areas.
  • Always define the source data set as dynamic extend before doing the PREINIT and leave as a dynamic extend until the move completes.
  • Check the Source max-blocks/tracks and make sure the target (PREINIT) data set is large enough.
  • An area can be moved once per MUF execution instance without an intervening database or area "close." If a second OAM is needed, the process must be delayed to a time when the database or area can be closed to MUF and then re-opened. Actions such as a MUF recycle or SHADOW MUF MIGRATE automatically close and re-open all databases which would enable subsequent OAM requests.
  • At the time of the OAM initiation the PREINIT (target) data set is opened. If it is smaller than the size of the current index or data area (see the following note), then the PREINIT target area is dynamically extended based on the dynamic extend options that are defined for the source area that is targeted for the move. The extend process repeats as needed until the size of the target data set is equal to or larger than the source area to be moved.
     For environments where the CXX option of ‘DATA HIGH USED MARK’ has been set to ‘YES’ (using the DBUTLTY CXXMAINT function), another check is made when checking the size of the source data set.
  • Each data area that is loaded using DBUTLTY function LOAD has an internal HIGH USED value. This value represents the DATA HIGH USED MARK that is the value of the highest block that was used for data storage since DBUTLTY loaded it. If this value is less than the size of the full source area, then the OAM only moves the data set blocks from the beginning of the source data set to this high-use point. Likewise, when OAM is checking the size of the PREINIT target data set, the target data set is only extended if it is not large enough to hold the source data set blocks to the high-use point. Currently, the specific high-use value is not externalized, but it is typically a value slightly higher than the ‘USED BLOCKS’ value on the DBUTLTY REPORT function with AREA=CXX and TYPE= A.
Determine source data set disposition
 
RENAME and SAVE
(Default) In the default option, the source data set is renamed once the OAM process is completed. This rename process adds a node to the existing data set name. The rename allows the old source name to be used for the new data set (previously target).
The added node is constructed with an “H” and a series of numbers and letters. This additional string is based on the z/OS "extended store clocks value" and should be unique.
In the unlikely case that the edited data set name already exists, the rename process fails. The OAM process issues a message stating that the rename DSN was not available. The data set is added to a list of data sets that are "delayed" in processing. Periodically, the MUF re-attempts the rename of the source data set with a new added node value so that the OAM process can be completed. For more information about this delay process, see Interruption and re-initiation of the Online Area Move process.
Once the rename of the old data set (source) completes, the new data set (target) is renamed to the original name. This process ensures that any existing JCL that includes the original data set names continues to work.
 
DELETE
(Optional) When the DELETE option is specified, the original source data set is un-cataloged and deleted.
Once the delete of the old data set (source) completes, the new data set (target) is renamed to the original name. This process ensures that any JCL that includes the original data set names continues to work.
Determine if backup is needed
While it is not required, some sites may want to take a DBUTLTY backup before starting the OAM process. This backup is similar to other "hot" backups. It provides a copy of the data that can be restored and used as a base for forward recovery processing. If a failure occurs and a recovery is needed, having a backup before the move process provides a good starting point.
Validate availability of MUF resources
To execute the required OAM processes, verify that there are enough available tasks and 24-bit storage.
  • Check the available 24-bit storage in MUF address space.
  • Ensure that MUF has available tasks. OAM runs in a MUF user task area.
  • Ensure that the area has a reasonable number of buffers available in MUF.
  • Do not start the OAM if any system or other activity is planned that can affect the OAM such as:
    • IPL
    • Activating a SHADOW MIGRATE
    • Starting a second Data sharing member (MODE A or B)
    • Attempts to run DBUTLTY single user jobs like BACKUP MULTUSE=NO
Start the ONLINE AREA MOVE
Once you are ready, the process to start the ONLINE_AREA_MOVE is a simple single-line command that is issued to the MUF.
Console command to start the ONLINE AREA MOVE
You can issue the ONLINE_AREA_MOVE command in one of the following ways:
 
Examples
 
/F MYMUF14, ONLINE_AREA_MOVE dbid,area-name /F MYMUF14, ONLINE_AREA_MOVE dbid,area-name,DELETE
 
Syntax
 
►─ ONLINE_AREA_MOVE dbid,area-name ──┬───────────┬──────────►◄ └─ ,DELETE ─┘
 
Parameters
 
 
ONLINE_AREA_MOVE
 
Requests an OAM.
 
 
dbid
 
 
Specifies the four-character database ID (dbid) of the area to move (valid values for dbid: 1- 5000).
 
 
,area-name
 
 
Specifies the area-name of the area to move (three characters, either IXX or a valid three-character area name).
 
,DELETE
 
(
Optional
) Tells the OAM the disposition of the original source data set.
DBUTLTY Parameters
Use the following commands for the DBUTLTY COMM CONSOLE function for an OAM.
 
Function:
 COMM
 
Syntax
 
► COMM OPTION=CONSOLE,OPTION2=’ONLINE_AREA_MOVE dbid,area-name ┬─────────┬’─►◄ └ ,DELETE ┘
 
Parameters
 
 
COMM OPTION=CONSOLE
 
Identifies the DBUTLTY function.
 
,OPTION2=’ONLINE_AREA_MOVE
 
Requests an OAM.
 
 
dbid
 
 
Specifies the 4-character DBID (dbid) of the area to move (valid values for dbid: 1- 5000).
 
 
,area-name’
 
 
The area-name of the area to move (three characters, either IXX or a valid three-character area name).
 If DELETE is used, the single quote mark (‘) comes after DELETE, instead of after the area-name.
 
,DELETE’
 
(Optional) Tells the OAM the disposition of the original source data set.
 
Examples
 
COMM OPTION=CONSOLE,OPTION2=’ONLINE_AREA_MOVE dbid,area-name’ COMM OPTION=CONSOLE,OPTION2=’ONLINE_AREA_MOVE dbid,area-name,DELETE’
SQL INSERT statement
Use the following commands for the SQL INSERT statement for an OAM.
 
Syntax
 
►─ INSERT INTO SYSADM.SQL_CONSOLE (MUF_NAME, CONSOLE_COMMAND) ────────────► ►─ VALUES (‘muf-name’, ‘ONLINE_AREA_MOVE dbid,area-name ─┬───────────┬ ’ ─►◄ └─ ,DELETE ─┘
 
Parameters
 
 
INSERT INTO SYSADM.SQL_CONSOLE (MUF_NAME, CONSOLE_COMMAND)
 
The SQL statement to insert a new row.
 
VALUES
 
Specify the values to use for the statement with the following parameters.
 
 
'muf-name
 
 
The name of the MUF being used.
 
 
dbid
 
 
Specifies the four-character database ID (dbid) of the area to move (valid values for dbid: 1- 5000).
 
 
,area-name'
 
 
The area-name of the source area (three characters, either IXX or a valid three-character area name).
 If DELETE is used, the single quote mark (') comes after DELETE, instead of after the area-name.
 
,DELETE’
 
(
Optional
) Tells the OAM the disposition of the original source data set.
 
Examples
 
INSERT INTO SYSADM.SQL_CONSOLE (MUF_NAME, CONSOLE_COMMAND) VALUES (‘muf-name’, ‘ONLINE_AREA_MOVE dbid,area-name’ INSERT INTO SYSADM.SQL_CONSOLE (MUF_NAME, CONSOLE_COMMAND) VALUES (‘muf-name’, ‘ONLINE_AREA_MOVE dbid,area-name,DELETE’
Sample DBUTLTY COMM OPTION=CONSOLE to issue ONLINE AREA MOVE
The JCL statements are for example only. Code all statements to your site and installation standards.
//OAM1022 JOB . . . //*-----------------------------------------------------------------** //JOBLIB . . . //*-----------------------------------------------------------------** //* ******************************************** //* OAM TO REO1022 TO THE TARGET AREA //* ******************************************** //OAMMOVE EXEC PGM=DBUTLTY //SYSIN DD * COMM OPTION=CONSOLE,OPTION2='ONLINE_AREA_MOVE 1022,REO' /*
Sample DBUTLTY COMM OPTION=CONSOLE output
Following are sample reports.
Date: 6/06/2014 ******************************************************************************** Page: 1 * CA Datacom/DB * Time: 13.45.07 * General Utility * Version: 14.0 * COPYRIGHT (C) 1990-2011 CA. ALL RIGHTS RESERVED. * ******************************************************************************** CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 COMM OPTION=CONSOLE,OPTION2='ONLINE_AREA_MOVE 1022,REO' FUNCTION=COMM OPTION=CONSOLE OPTION2=ONLINE_AREA_MOVE 1022,REO
Date: 6/06/2014 ******************************************************************************** Page: 2 * CA Datacom/DB * Time: 13.45.07 * General Utility * Version: 14.0 * COPYRIGHT (C) 1990-2011 CA. ALL RIGHTS RESERVED. * ******************************************************************************** Directory: QAMUF4
Sample OAM messages n MUF job log
The following sample report shows messages that the sample console command (shown previously) triggers.
DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS PREPARING TO START DB00102I - ENDED JOB-OAMREO14 NUMBER--5971 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS STARTED DB02819I - ONLINE_AREA_MOVE 1022 REO MOVED BLOCK 1 OF 3,600 DB00102I - ENDED JOB-OAMREO14 NUMBER--5972 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS BLOCKS MOVED, START CLOSE-OPEN DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS VOLUMES FROM 1 DCMSP2 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS UNCATALOG DCMQA.QAMUF4.REO1022 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME FROM DCMQA.QAMUF4.REO1022 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME TO DCMQA.QAMUF4.REO1022.H0CE6B64 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS CATALOG DCMQA.QAMUF4.REO1022.H0CE6B64 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS VOLUMES FROM 1 WRKD24 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME FROM DCMQA.QAMUF4.REO1022.ASOF0607 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME TO DCMQA.QAMUF4.REO1022 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS COMPLETE, AREA STILL OPEN
ONLINE_AREA_MOVE process flow
Issuing the ONLINE_AREA_MOVE command results in:
  • Command syntax is validated and accepted.
  • Area (source) and PREINIT (target) status is checked.
  • ONLINE_AREA_MOVE command is accepted. The move started message is written to the MUF job log. The PREINIT entry in the CXX is removed as the target data set is now part of an active OAM process.
  • Multiple status messages are written to the MUF job log during the movement of blocks.
  • Once the blocks are all moved, the MUF user processing to the area being moved is paused.
  • The area is briefly closed to MUF.
  • z/OS data set renames are done and messages are written to the MUF job log.
  • Move complete message is written to the MUF job log.
  • The area is opened to MUF.
  • The user processing to the area is re-activated.
The OAM task runs in MUF and has both the source and target data sets open as shown in the following graphic.
  MyMUF14.PNG  
Monitor the Online Area Move process
The OAM functionality begins by establishing control information in the source and target data sets. A temporary I/O director is created to manage user requests for data that may come in while the move process is running.
The OAM process then begins to move the physical blocks on the source data set to the target data set as fast as possible. For data areas, the move process can move groups of blocks (up to a track) at a time. For index areas, the move process is limited to a block at a time. Each time a move process is complete, the control information is updated to reflect the current location of the data blocks. The I/O director uses this control information to direct ongoing user data access requests.
The OAM process continues until all the blocks in the source data set have been moved to the target data set.
During the OAM process, a series of messages are written to the MUF job log/console showing the ongoing progress of the OAM. The following example shows a series of messages.
During the OAM start process, the PREINIT information is copied into the ONLINE AREA MOVE and deleted from the CXX PREINIT section (TYPE=P Report).
The blocks moved message is issued for the first block and repeated about every 2 minutes until all blocks are moved.
DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS PREPARING TO START DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS STARTED DB02819I - ONLINE_AREA_MOVE 1022 REO MOVED BLOCK 1 OF 3,600 DB02819I - ONLINE_AREA_MOVE 1022 REO MOVED BLOCK 3001 OF 3,600
Complete the OAM
After all blocks are moved, the OAM process starts pausing all user access to the area and closing the area within MUF. The necessary steps are performed to rename or delete the original source data set and then rename the target data set to the original source name.
ONLINE_AREA_MOVE 1022 REO STATUS BLOCKS MOVED, START CLOSE-OPEN DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS VOLUMES FROM 1 DCMSP2 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS UNCATALOG DCMQA.QAMUF4.REO1022 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME FROM DCMQA.QAMUF4.REO1022 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME TO DCMQA.QAMUF4.REO1022.H0CD5FA6 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS CATALOG DCMQA.QAMUF4.REO1022.H0CD5FA6 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS VOLUMES FROM 1 WRKD01 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME FROM DCMQA.QAMUF4.REO1022.ASOF0606 DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS RENAME TO DCMQA.QAMUF4.REO1022
If the OAM process is unable to complete the rename/delete activity for the source and/or target data sets, an error message is issued and the OAM process in placed in a “wait” state. The rename/delete is re-attempted every 2 minutes until the OAM process successfully completes the rename/delete process.
Once all the rename/delete activity is complete, the area is made available to the MUF and the paused processing is resumed. A final message is created indicated the status is complete and the moved area is open to processing in MUF.
DB02818I - ONLINE_AREA_MOVE 1022 REO STATUS COMPLETE, AREA STILL OPEN
Determine if area backup is needed
While it is not required, some sites may want to take a DBUTLTY backup after completing the OAM process. This backup is only used if a failure occurs after the OAM completes and there is a requirement to restore the area to a previous backup.
Additional Considerations
The following topics are important to successfully using the OAM process.
Performance monitoring based on requests per IO
Performance monitoring and tuning typically measures the amount of CPU and IO performed for a given set of requests or functions. The OAM is an IO intensive task with a single database request running inside MUF. The single request generates significant physical IO and CPU usage. Therefore, it can affect performance measurement metrics that may be in use at your site such as:
  • Requests per CPU second
  • Requests per physical IO
  • Other types of job cost accounting
The processing that OAM performs is similar to what we already experience with the OLREORG functions of DBUTLTY.
Since the OAM process is normally not a daily occurrence, there may be no significant effect in overall processing metrics for your site. However, when there is a need for multiple OAM processes, make sure that the OAM is accounted for in your performance metrics.
Recommendations for measuring and adjusting for the OAM activity include:
  • Schedule the OAM activity for a period where there is light user activity.
  • Use tools such as DBUTLTY AutoCollect and AutoInfo snapshots to collect performance information before and after the OAM processes. These tools allow adjustment to the overall performance metrics.
  • Consider using the accounting facility to trap the OAM (and OLREORG) activity so that overall performance metrics can be adjusted.
 
Important!
 Making any tuning changes that are based on collected statistics while processing an OAM is not recommended. These statistics may not reflect normal workloads.
Interruption and re-initiation of the Online Area Move process
The OAM process executes in a MUF task area and can be executed with other workload being processed within the MUF. The goal for the DBA or system programmer is to schedule execution of the OAM when it is highly probable that the OAM work can be completed without interruption.
However, situations can occur where the OAM process is interrupted. This section describes how OAM functions if it is interrupted.
QUIESCE
Use the MUF QUIESCE process to place a MUF in a “quiesced state” and force all pended (in memory) updates out to the DASD data sets.
OAM must honor the MUF QUIESCE command (both QUIESCE REQUEST and QUIESCE TRANSACTION).
For example:
  • User issues a QUIESCE command to the MUF
  • Each active MUF task is told to QUIESCE or "go to sleep"
  • OAM will:
    • Complete in-flight move process
    • Update source and target control blocks
    • Go into a “wait” mode
    • Tell QUIESCE that we are now “sleeping”
Once the QUIESCE is in place, you can now perform the system functions that triggered the need for the QUIESCE. In most cases, this is some type of DASD backup process. If an OAM is in process, make sure that the backup process captures both the source and target data sets at the “same consistent” point.
If the backup is used to restore an area at some future point, restore both the source and target data sets from this same consistent point.
  • Once the backup process is completed, issue the QUIESCE OFF command to the MUF.
  • QUIESCE OFF - wakes up OAM and the move process continues where it left off.
REQABORT
Use the REQABORT command to interrupt the OAM process if there is an emergency. Issuing a REQABORT forces the OAM to stop processing at a stable point, terminate the process, and free up the MUF task area.
For example:
  • User issues a REQABORT command for the OAM process in MUF.
  • MUF tells the OAM task to get to a stable point and then terminate.
  • OAM:
    • Completes in-flight move process.
    • Updates source and target control blocks.
    • Writes a message to the MUF job log indicating that the OAM was aborted.
    • Ends the process and releases the MUF task area.
  • The REQABORT of the OAM does not affect other MUF processing. User processes accessing the partially moved area continue as before.
Because the OAM is incomplete, both source and target data sets remain in use by the MUF and only MULTUSE=YES utility functions are allowed to execute.
Single-user jobs cannot access the area until the OAM is re-initiated and completes successfully.
CLOSE
In certain cases, you may need to close a database or area while an OAM is executing. If the CLOSE command is issued for the area being moved, the OAM process is terminated.
For example:
  • User issues a CLOSE command for the database that the OAM is processing.
  • The CLOSE tells the move task to get to a stable point and then terminates.
  • OAM will:
    • Complete in-flight move process
    • Update the source and target control blocks
    • Write a message to the MUF job log indicating that the OAM was stopped
    • End the process and release the MUF task area
The CLOSE of the database terminates all MUF processing for this area. Since the OAM is not complete, both the source and target data sets must remain.
Single-user jobs cannot access the area until the OAM is re-initiated and completes successfully.
 
More information:
 
How to re-initiate the Online Area Move process
For both REQABORT and CLOSE, the same process is used to restart the OAM. You can re-initiate the OAM by performing one of the two following steps:
  1. Reissue the ONLINE_AREA_MOVE command. This task:
    • Opens the area in MUF (source data set).
    • Verifies that everything is still in place (opens target data set).
    • Issues a MUF message that the OAM is restarting.
    • Restarts the move process where it left off.
      2. Close the area to MUF and re-OPEN the area (or database).
  • Triggers a restart of the ONLINE_AREA_MOVE command.
  • Opens the area in MUF (source data set).
  • Verifies that everything is still in place (opens target data set).
  • Issues a MUF message that the OAM is restarting.
  • Restarts the move process where it left off.
RESTART
If the MUF fails while an OAM is occurring, the data set control blocks stored within the source and target data sets provide the restart point for the OAM. There is no requirement for the RESTART log file processing to resolve any in-doubt or uncommitted data set block moves that were in process by OAM.
Tables within the area may have been actively processed by other tasks that do require a resolution. Therefore, the standard RESTART processing of the log file searches for updates to the data tables that must be reprocessed to a stable point.
If it is determined during the restart processing of log transactions that this area needs to open to reprocess the logged transactions, that open triggers the re-initiation of the OAM process.
If the restart processing of log transactions does not need to open the area, the re-initiation of the OAM process is not triggered until:
  • another process opens the area or
  • another ONLINE_AREA_MOVE command is issued for this area
Because the OAM is incomplete, both the source and target datasets remain in use by the MUF. Only MULTUSE=YES utility functions are allowed to execute against this area until the OAM is re-initiated and completes successfully.
Exception handling - area (data sets) being moved cannot be renamed or deleted
 
Important!
 This condition is not expected but it is possible.
For MUF to delete or rename the data sets that are involved in the OAM, z/OS requires that the DSN not be in use by any DD statement for an executing Job within this LPAR or SYSPLEX.
MUF and DBUTLTY normally dynamically allocate index areas and data areas as needed. In this normal case, when an OAM completes, the MUF completes the process by deleting or renaming the data sets as needed.
If MUF requests the delete or rename and the data sets are not available due to another job using one or both, z/OS generates messages to the MUF JES log reflecting the condition and the rename/delete fails. MUF cannot prevent these messages and indeed they are important for you to see the condition.
Should this occur, MUF recognizes the rename/delete failure and issues a message indicating that the OAM rename/delete failed due to ‘DSN NOT AVAIL.’.
MUF places the area on a list of areas that have all blocks moved but cannot be deleted or renamed. The MUF checks every 2 minutes (approximately) to see if the DSN appears to be available. If not available the ‘DSN NOT AVAIL.’ message is re-issued to the MUF JES log and the area rename set for another retry.
If available, the delete or rename is tried again.
The RESTART process reactivates this 2-minute process if the MUF fails while the data set rename is still waiting to process.
Exceptional condition - system outage occurred during area (data sets) rename or delete
 
Important!
 This condition is not expected but it is possible.
During the OAM process of deleting or renaming a data set there could be a System outage or error. The process must update the catalog and the VTOC on each volume containing the data set. This is true for the old area and the new area.
If an outage occurs during this critical time, a new MUF execution cannot correct the condition. You receive OPEN errors when the MUF is unable to find needed catalog entries for the data sets.
In this case, manually research the action that was interrupted and complete it. This includes deletion from the catalog, deletion of the data set on DASD, addition to the catalog, and rename of the data set on DASD. The MUF messages provide the action that was being performed and the information that would be needed if such an event were to occur.
How to abandon the Online Area Move process
The OAM function is powerful and allows you to move data sets without interrupting access to your data. Therefore, a certain amount of planning and forethought is required.
However, if you decide that you must abandon an OAM before it completes, it requires that the user data access is interrupted. Plan the use of OAM at a time where there is high confidence that the process can complete.
Data area
In the event, that an OAM of a data area must be abandoned, the following steps are required.
  1. REQABORT the OAM.
  2. ACCESS OFF the database or area.
  3. Acquire a current backup of the data area by running a DBUTLTY BACKUP SEQ=PHYSICAL with MULTUSE=YES and RECID=YES. A previous backup is OK if you are willing to run FORWARD RECOVERY.
  4. Delete and reallocate the original data set to new size, volume, and so forth, by performing a DBUTLTY INIT on the data area if needed.
  5. Perform a normal DBUTLTY LOAD of the backup.
  6. Run recovery (if needed).
  7. Open the database/area.
  8. Validate/testing to help ensure that everything is OK.
  9. Delete the allocated target data set from z/OS.
Index area
If an OAM of an index area must be abandoned, the following steps are required:
  1. REQABORT the OAM.
  2. ACCESS OFF the database.
  3. If needed, delete and reallocate the original data set to new size, volume, and so on, by performing a DBUTLTY INIT on the index area.
  4. Run a full database RETIX.
  5. Open the database/area.
  6. Validate/testing to help ensure that everything is OK.
  7. Delete the allocated target data set from z/OS.
DBUTLTY and ONLINE AREA MOVE
OAM is a MUF-centric task that is running against the area. Once the OAM begins processing, both the source and target data sets are in-use. At any given point, a certain block in the area may be in the process of moving from the source to the target.
To allow other MUF tasks to continue accessing the user data that is stored in the moving area, a special piece of code is activated in the MUF address space. This special code (I/O Director) manages the data access to the moving area and ensures that the correct data set is accessed for the most current version of the data set block.
Single-User tasks run outside the MUF address space and access the area data sets directly using information the CXX data set provides. These single-user functions do not have access to the buffers and information in the MUF address space. They cannot access the IO Director and any attempt to access the data set of the area directly would result in incomplete or incorrect information.
Therefore, no single-user DBUTLTY execution is allowed against an area that has an OAM in process. Any attempt to access the area fails with an appropriate return code.
A set of DBUTLTY functions can execute within the MUF address space or in concert with the MUF address space (MULTUSE=YES). Of this set of functions, only those functions that execute in a non-destructive form can execute while the OAM is executing.
DBUTLTY area functions to avoid
Various DBUTLTY functions can process the index or data area while the OAM is executing. We recommend that they be delayed until after the OAM has completed.
This type of utility function can work within the MUF and works in concert with the OAM. However, these utility functions normally use the same resources that the OAM is using. In some cases, these resource contentions could significantly slow down the OAM process.
Allowable DBUTLTY functions
As stated in the DBUTLTY area functions to avoid topic, all DBUTLTY functions should be avoided while OAM is active. However, a subset of the DBUTLTY functions can be executed against a data area while an OAM is moving the area including:
  • BACKUP SEQ=PHYSICAL (with MULTUSE=YES)
  • DBTESTR (with MULTUSE=YES)
  • DEFRAG
  • EXTRACT SEQ=PHYSICAL (with MULTUSE=YES)
  • LOCK
  • MASSADD (with MULTUSE=YES)
  • OLREORG (does not use MULTUSE=YES keyword)
  • QUIESCE
  • REPORT AREA=CXX
  • REPORT AREA=IXX
  • REPORT TYPE=DATANE
  • REPLACE
  • RETIX KEYNAME=*SETR (does not use MULTUSE=YES keyword)
  • DATASCAN OPTION=REBUILD_SPACE_INDEX (does not use MULTUSE=YES keyword)
  • UNLOCK
New console command - STATUS_OAM
This new command is only available through the z/OS modify (/F) command support.
 
‘/F mufname,STATUS_OAM’
 
The status command asks MUF to provide information on any active OAM process. This includes any OAM process that has passed the point of basic command editing up until the time the OAM is ‘fully complete’ and no longer known to MUF.
This ‘fully complete' condition means that the database or area has been closed to MUF after the OAM completion. The new target data set is the only data set known to the MUF.
The status information is displayed as a single MUF message, DB02820. With the format of the message as:
DB02820I - ONLINE_AREA_MOVE STATUS_OAM 
dbid area-name variable-info
 
In the message:
  • The ‘dbid’ is replaced by a Datacom Database ID, a number from 1 through 5000.
  • The ‘area-name’ is replaced by the 3 character area name being moved.
  • The ‘variable-info’ is replaced by one of the possible current status conditions.
Messages
You could receive messages during your OAM. The message types are:
  • Progress
  • Status
  • Error
Progress Message DB02819I
 
ONLINE_AREA_MOVE 897 C01 MOVED BLOCK 1 OF 60
 
 
Reason:
 
This informational message can occur for the following reasons:
  • When the move starts to show the start and the number of blocks that are subject to the move
  • If the move is restarted to show blocks remaining to be done
  • To show progress about once every 2 minutes
The message format varies after the initial occurrence of ‘BLOCK 1 of’. The message uses TRACK ‘n’ OF ‘n’ for datasets that are bigger than 9,999 tracks. The message uses CYLINDER ‘n’ OF ‘n’ for datasets that are bigger than 9,999 cylinders.
 
Action:
 
None.
Status Message DB02818I
 
 
ONLINE_AREA_MOVE 
dbid area
 STATUS - 
variable-info
 
 
 
 
Reason:
 
This informational message provides the following variable information:
 
BLOCKS MOVED, START CLOSE-OPEN
 
Reflects that the block movement is done and the two data sets were updated to reflect all blocks have been moved. After the old rename/delete process is successfully completed, the next process uses an IO gate to:
  • Temporarily stop all I/O activity to the new area
  • Close the data sets
  • Perform the new data set rename process
Once complete, the area is reopened in MUF with just the new (target) data set being used, the IO gate is removed, and I/O activity resumes. The amount of time that the IO gate is active is likely to be sub-second and is not likely to be detectable.
Messages, if activated, show how this close and remove occur as the actions take place.
 
COMPLETE, AREAS STILL OPEN
 
Reflects that the block movement is done and the two data sets are updated to reflect all blocks have been moved. The old (source) data set has been renamed or scratched. The new (target) data set has been renamed to the original (source) name. The future executions of DBMUFPR or DBUTLTY will only open the original name pointing to the new data set. All I/O requirements are directed to the new data set. While the move is complete, the area is still open to this MUF execution as a moved area. Therefore, this status remains until the MUF is terminated or the moved area is subject to a CLOSE.
 The only reason to perform a database or area CLOSE to complete the OAM process is to allow a new OAM process of the same area to start. One case is where 24-bit storage is limited to free the 24-bit storage that is used for the old source dataset information. For most cases, waiting until the next recycle of MUF to clear this old information and reset this status would be sufficient.
 
PREPARING TO START
 
Reflects that a task area has been allocated to perform the area move and it is just starting.
 
RESTARTED
 
Reflects that the area move was stopped for one of several reasons and is now being restarted.
 
STARTED
 
Reflects that the additional editing required during the prepare process has completed successfully. Any dynamic extend needed for the new target area to be as large as the move source area has also completed.
 
VOLUMES FROM 1 WRKD19 WRKD18, WRKD09 WRKD01
 
Reflects that the OAM has completed the move of all blocks and is in the process of first renaming the old (source) data set or, later the new (target) data set. Each of the volumes that the area is cataloged on (old or new) is printed. It is important for MUF to correct all data set extents on all volumes.
The ‘FROM 1’ reflects that the VOLSER values provided start from the first one. The line provides the first 6 VOLSER values. If more exist, then the message repeats for the VOLSER values ‘FROM 7’. This process continues up to the maximum of 59. This example has 4 VOLSER values.
 
SCRATCH DCMQA.QSMUFM.AR1317
 
This message is paired after the previous message with VOLUMES. The value of SCRATCH and the data set name are to provide the old (source) data set name. It is the only one that can be set to DELETE causing the SCRATCH. If the SCRATCH is successful, the process continues with the UNCATALOG process. Otherwise, error messages occur and the OAM delay/re-initiation process is invoked.
 
UNCATALOG DCMQA.QAMUFM.AR1317
 
This message is paired after the previous message with SCRATCH. The value of UNCATALOG and the data set name are to provide the old (source) data set name. If the UNCATALOG is successful, the process continues with the UNCATALOG process. Otherwise, error messages occur and the OAM delay/re-initiation process is invoked.
 
RENAME FROM DCMQA.QAMUFM.AR23319.NEW1
 
This message is paired after the previous messages. The value RENAME FROM provides the dataset name that is being renamed.
 
RENAME TO DCMAQ.QAMUFM.AR23310
 
This message is paired after the previous messages. The value RENAME TO provides the data set name that the FROM is being renamed to. Both are for the VOLSER list in a previous message.
 
Action:
 
None.
Error Message DB02817E
ONLINE_AREA_MOVE 
dbid area
 ERROR - 
variable-info
 
 
Reason:
 
This message is generated for a failed OAM request. Variable-info text could be:
 
ALREADY ACTIVE
 
Reflects that the area to be moved is already active in a previous OAM that has not fully completed. The index and data areas must be subject to a database CLOSE before being processed by a subsequent OAM. This includes another task area that is also starting a move.
 
AREA NAME ?XX
 
Reflects an area name was provided that ends in 'XX' that is not available to be moved. For example, PXX or RXX.
 
AREA NOT FOUND
 
Reflects that the particular area could not be found in the CXX.
 
AREA NOT URI
 
Reflects a data area that was selected for the OAM is currently loaded with URI=NO. This type of area cannot be moved.
 
BASE CLOSED
 
Reflects that the database was subject to a COMM CLOSE command during an active OAM. The close process directs the OAM process to be stopped at its current location. This is reflected as an error to OAM as it is stopped and the area is left in a partially moved state. The area remains in this state until the OAM is restarted by a future process.
 
CLOSE DISPOSITION error(error)
 
Reflects that the move has completed and all blocks were moved. OAM has encountered an error during the process of the internal close rename/delete handling. This handling includes:
  • Close of the area moved
  • Removal of the DD statement for the source data set
  • DEQ of the data set name protected
  • Scratch (delete) of the source data set and uncatalog of the source data sets, or rename of the source data set
  • Rename of the target data set
The return code reflects a specific error.
 
COMPLETE, OPEN
 
Reflects that an OAM request has been requested for an area that has already been subject to a completed OAM. For example, one that has completed all block moves and has also completed all close dispositions. All move requirements have been completed. The currently executing MUF can only move the area a second time if the area is closed using the database CLOSE command to the MUF.
 
CXX SHARING
 
Can no longer occur as the X_CXX_ALLOW_SHARING option has been deprecated and is now ignored.
 
DD PRESENT
 
Reflects that the MUF was executed with JCL including the DD statements for the index or data area. This is not a best practice and the move is not designed to work in this configuration. The normal execution is to allow the MUF to dynamically allocate all index and data areas it might need based on the data set name that is known to the Directory CXX.
 
DELAY REQABORT
 
Reflects that the move was stopped using a REQABORT command. The online move delay parameter should only be used with Broadcom Support during debugging operations. Use of online move delay in normal operation is strongly discouraged and is not a best practice.
 
DELAY_SEC
 
Reflects that an internal error stopped the move during use of a testing option ‘X_ONLINE_MOVE_DELAY_SEC n’. The online move delay parameter should only be used with CA Datacom support during debugging operations. Use of online move delay in normal operation is strongly discouraged and is not a best practice.
 
EOJ SET
 
Reflects that the OAM process was stopped because a MUF EOJ command has been requested and the MUF shutdown process is beginning. Use of an EOJOFF command to cancel the EOJ request does not restart the OAM process. If EOJOFF is done, you must restart the OAM process by issuing a new OAM command for each OAM process that stopped.
 
EXTEND LOCK
 
Reflects a condition that should not occur. It would mean that the area to be moved is not available to an internal lock used to extend an area. If this error occurs, contact Broadcom Support.
 
GETUP error(error)
 
Reflects a condition that should not occur. It would mean an internal command that was used as part of the OAM has failed with a DB return code as documented with the external and internal error numbers. If this error occurs, contact Broadcom Support.
 
GSETP error(error)
 
Reflects a condition that should not occur. It would mean an internal command that was used as part of the move has failed with a DB return code as documented with the external and internal error numbers. If this error occurs, contact Broadcom Support.
 
INDEX MOVE
 
Reflects a condition that should not occur. However, it would mean that an internal error in moving an index block has failed with a DB return code. The error should have been documented with a Master List dump. If this error occurs, contact Broadcom Support.
 
INVALID NEW CONTROL BLOCK
 
Reflects that the PREINIT area was found and opened. However, it does not currently contain correct information for the area that OAM has targeted, specifically the same DBID, and same area name.
 
MUFPLEX
 
Reflects that the MUF is running in full MUFPLEX data sharing mode and the move may not start. A previously started move will not make progress. However, the two physical MUF regions fully support the partial move with the two data sets each containing part of the data of the area.
 
NO MEMORY
 
Reflects that the move process was unable to get memory to start the actual move.
 
NO PREINIT
 
Reflects that the area to be moved does not have a pre-initialized area in the current list of PREINIT areas. The DBUTLTY function REPORT with AREA=CXX,TYPE=P provides the current areas available.
 
NOOPT
 
Reflects that the database containing the area to be moved is defined as ACCESS NOOPT and the move may not start.
 
NO TASK
 
Reflects that the MUF has no task area available for starting the move process.
 
OPEN FROM error(error)
 
Reflects the old (source) data set to be moved could not be opened. The specific error is provided with the external and internal error numbers provided.
 
OPEN to error(error)
 
Reflects the new (target) data set could not be opened. The specific error is provided with the external and internal error numbers provided.
 
OPTION DELETE
 
Reflects the ‘ONLINE_AREA_MOVE dbid,area-name’ has additional text but that text is not ‘,DELETE’ which is the only option.
 
PREINIT DELETE ERROR
 
Reflects a ‘soft error’ where the move attempted to delete the PREINIT data set information from the Directory CXX but the delete failed for some reason. Information about the error was provided but the OAM process continues.
 
PROCESSING MOVE error(error)
 
Reflects that the move has started moving blocks but received a return code (external and internal) that has stopped the move.
 
READ CXX error(error)
 
Reflects that the move has gotten an error during CXX processing receiving a return code (external and internal) that has stopped the move.
 
REOPEN error(error)
 
Reflects that the move has completed the block moves and the close disposition (scratch, delete, rename, uncatalog, catalog) as needed but then had an error reopening the new area under the original name. This error condition is significant as the new area will not reopen and allow user access.
 
TOO FEW BUFFERS
 
Reflects that the move has been requested in an environment that has too few data buffers for the move to be successful. Buffer requirements for index areas and data areas is documented with the move process.
 
UNABLE TO EXTEND error(error)
 
Reflects that the PREINIT area was found and opened and contains the proper information. However, it was initialized with a smaller number of tracks and a dynamic extend failed to acquire as many tracks needed to complete the move. This error specifically indicates the inability to acquire more space from z/OS.
 
UNABLE TO START error(error)
 
Indicates that similar to the UNABLE TO EXTEND message, another error occurred while trying to extend the target area. A specific message would have been issued to provide the specific error that occurred.
 
Virtual
 
Reflects that the database containing the area being selected for the OAM is defined as VIRTUAL and the move may not start.
 
WRONG BLOCK SIZE
 
Reflects that the PREINIT area was found but it was defined with a BLKSIZE different than the area to be moved. The move requires the same block size in both source and target data sets to allow a block by block copy. Redefine the target area with a new PREINIT function with the correct block size and the move requested again.
 
WRONG OLDEP SETTING
 
Reflects that the PREINIT area was found with the OLDEP=YES/NO option set different than the index area being selected for the OAM. Both the source and target datasets are required to be the same. The target area must be subject to a new PREINIT with the OLDEP setting the same as the old source area.
STATUS_OAM Message DB02820I
ONLINE_AREA_MOVE STATUS_OAM 
dbid area variable-info
 
 
Reason:
 
This informational message occurs in support of the STATUS_OAM console (only) MUF command. The variable-info may contain one of the following:
 
COMPLETE, AREA STILL OPEN
 
The area blocks have been all moved and the data set subject to either the scratch and rename or the rename and rename. All is complete except that the area has not been subject to a CLOSE since the move and so a new move is not allowed.
 
ALL TRACKS MOVED, WAITING DSN
 
The area blocks have been all moved and the data set is waiting for the ability to start the scratch and rename or the rename and rename process.
 
ALL TRACKS MOVED, NEXT SCRATCH/RENAME
 
The area blocks have all moved and the data set is waiting for the scratch and rename process to complete. The data set name (DSN) was not available exclusively when that last attempt was made.
 
MOVE TASK STOPPING
 
The move is in process with a task area assigned and it is currently in the process of stopping. It might have moved all blocks or might be stopping because the area is in the process of being closed.
 
MOVE TASK RUNNING
 
The move is in process with a task area assigned and it is preparing to move or doing the move.
 
PARTIAL MOVE BUT NO CURRENT TASK
 
The area has been started before and so is partially moved but is not currently being moved as there is no task area assigned to continue the move.
 
MOVE STARTING
 
The move is in the process of starting
 
Action:
 
None.
Other Message Changes - new internal rc added to db rc 94
Database return code Return code 94(176)
 
Reason:
 
A single-user function (DBUTLTY) is trying to open an index or data area that the Multi-User OAM process is processing.
 
Action:
 
The OAM process must complete before any single-user jobs can be executed against the area.
Other Message Changes - format
Standard and optional messages for OAM can reflect an area name with DBID as a DDNAME. They correctly show either:
  • The normal style of the area name and 3-4 position DBID
  • A move-to area with the area name and a five position DBID
Return code processing during Online Area Move
Return code processing for OAM tasks is processed the same as other tasks receiving return codes with one exception. Resolving an error that occurs during an OAM operation may require information that is only available in a Master List dump. Therefore, an OAM task that encounters an error that would normally not produce a dump of the Master List instead has a Master List dump forced with a reason of “PATCH".