MASSADD (Add Records to Table)

The MASSADD function communicates with one Multi-User Facility (MUF).
datacom151
The MASSADD function communicates with one Multi-User Facility (MUF). Consider the following:
  • Ensure that DBUTLTY is communicating with the MUF that you want by executing DBUTLTY with the same System Identifier module (DBSIDPR) that the MUF is using
  • Ensure proper load library concatenation by keeping the System Identifier modules (DBSIDPR) in separate load libraries.
If the z/OS Cross-System Coupling Facility (XCF) is being used, ensure that the TOGROUP DBSIDPR parameter is correctly defined. 
When to Use MASSADD
Use the MASSADD function to add a large volume of records to a table. Some application systems can be designed to accumulate records during daily online processing that are added in a single batch run during non-prime hours. Use MASSADD to perform this maintenance without having to write a specialized application program.
Use of Pipeline
MASSADD takes advantage of the Pipeline high-performance maintenance feature of 
CA Datacom®/DB
. The function issues warning messages if logging is not active. 
Log Check Points and Backout
In the MUF, when logging is on for this table, MASSADD issues a LOGCP every 1000 records. A message is displayed with a record count each time a checkpoint is taken. The function generates a User Requirements Table (URT) with transaction backout specified. MASSADD offers a restart capability to allow you to begin processing the input records at the exact point of any failure.
Unique Keys
By default, the MASSADD function terminates with error message DB13037E identifying the record and a return code 10. Asmall snap dump is generated if you attempt to add a record with a duplicate value for a key which is defined to be unique. For information about reading the snap dump, see Using Dumps in Problem Determination. Transaction backout is not invoked when this condition is encountered. However, you can execute the MASSADD function with the STARTAFT= parameter which allows you to specify a number of records to skip in the input data set.
OPTION2 allows you to ignore duplicates, both the return code 10 as above and also return code 94 (193) duplicate unique key definition. You can set OPTION2 as OPTION2=DUPS_IGN to direct that any duplicates are to be counted and simply ignored. Or, you can set OPTION2=DUPS_DD where any duplicates are to be counted, written to an output file with a DDNAME DUPSTTT.  The TTT is the table name, and ignored. The format and requirements of the DUPSTTT file are the same as the output to a DBUTLTY function EXTRACT. With the OPTION2 set as above, a duplicate is not considered an error and the function completes not as an error. The report is altered if OPTION2= is specified with either of the DUPS_ values to provide the following:
  • Number of input rows 
  • Number of rows added 
  • Number of rows ignored
With the OPTION2 keyword set as DUPS_DD, the output data set is opened and if no duplicates occur is closed with no rows.
 OPTION2 is a valid keyword only if MULTUSE=NO is not specified where the MASSADD directs the adds to the MUF environment.
Integrity Constraints
When executing through the MUF, the MASSADD function enforces any integrity constraints defined for a table.
If you attempt to add a record which contains invalid data for any field which is defined in 
CA Datacom® Datadictionary™
 with DBEDITS=Y, the MASSADD function terminates with an error message.
If any field in the table is defined in 
CA Datacom® Datadictionary™
 with the FORCEADD=Y attribute-value, the MASSADD function is treated as an application adding records to the table and new values are set for the fields.
Use of the MUF
MASSADD can perform the add requests either through the MUF or as a Single-User task. Run MASSADD through the MUF to add records to a table defined with integrity constraints.
We recommend that you run MASSADD with the MUF to take full advantage of the normal RESTART and RECOVERY options, since the logging facility is not available in Single User mode. If you use Single User mode, checkpoint messages do not occur and transaction boundaries are not provided. If the utility fails, a log file does not exist to be restarted to ensure that the data and index are synchronized. If you do not use the MUF, back up the area before running the MASSADD function. You can reload the backup and try again if the function does not complete.
Tables Using DBVVRPR
The MASSADD function does not support adding records to tables defined with a user compression exit name (DBVVRPR).
Successful Execution Requirements and Controls
 
Environmental
 
Requirements
 
when MULTUSE=NO, Simplify NO, or MUF down
 
  • The database may 
    not
     be open for update anywhere.
  • The database may 
    not
     be open in any MUF for read.
  • The database may 
    not
     have any table in 
    unloading
     status.
 
Environmental 
 
Requirements
 
 when MULTUSE=NO, Simplify YES, and MUF enabled
 
  • The database may be open for update but must have no users.
 
Environmental
 
Controls
 
when MULTUSE=NO, Simplify NO, or MUF down
 
  • The database will be opened for update.
  • The utility has no knowledge about current ACCESS database or area status.
  • The utility sets no ACCESS database or area status.
 
Environmental 
 
Controls
 
 when MULTUSE=NO, Simplify YES, and MUF enabled
 
  • The database will be opened for update if not already.
  • All areas will be closed if open.
  • The utility will execute with every ACCESS database or area status.
  • The utility sets protection to block other incompatible DBUTLTY functions
 
Environmental
 
Requirements
 
when MULTUSE=YES
 
  • The database may or may not be open for update in the connected MUF.
  • The database may 
    not
     be open for update in another MUF or Single User job.
  • The database may 
    not
     have any table in 
    unloading
     status.
  • The database ACCESS must be set WRITE/UTLTY.
  • The area ACCESS must be set WRITE/UTLTY.
  • The area may 
    not
     have BACKUP, EXTEND, EXTRACT, INIT, LOAD, RECOVERY, REORG, REPLACE, or RETIX with MULTUSE=YES executing.
 
Environmental
 
Controls
 
when MULTUSE=YES
 
  • The database will be opened by MUF for update.
  • The utility does 
    not
     set ACCESS area.
  • The utility does 
    not
     set MASSADD executing this MUF this database or area.
How to Use MASSADD
MASSADD can run in Single User mode if NO is specified for the MULTUSE= keyword. Execute DBUTLTY using the following command format:
►►─ MASSADD DBID=
n
,DDNAME=
d
,TABLE=
t
──────────────────────────────────────────► ►─┬───────────────────────────────────────────────────────┬────┬──────────────► └─ ,MULTUSE = ─┬─ YES ◄ ─┬────────────────────────────┬─┤ | | | └─
,OPTION2=
┬ DUPS_IGN──────┤ | | | | └─ DUPS_DD ─────┘ | | | └─ NO ───────────────────────────────────┘ | | | └─ ,OPTION2= ─┬──────────────────┬───────────────────────────┘ ├─ DUPS_IGN ──────┤ └─ DUPS_DD ────────┘ ►─┬─────────────────────────────┬──┬──────────┬───────────────────────────────►◄ └─ ,STARTAFT= ─┬─ 0 ◄ ──────┬─┘ └─ ,PRTY=n─┘ └─
nnnnnnnn
─┘
 
Command
 
  •  
    MASSADD
    Invokes the function to accept input records for a single table and add those records to the table.
 
Required Keywords
 
  •  
    DBID=
    Specifies the databLimit
    Valid Entries:
    • DATACOM-ID of the database
    •  
      Default:
      (No default)
  •  
    ,DDNAME=
    Specifies the JCL DDname of the input data. If the input source is a VSAM file, 
    CA Datacom®/DB
     processes it as an ordinary file.
    A DDNAME is not acceptable
     
    for sequential input or output files if it is a name reserved for a 
    CA Datacom®
     area. Names with the following patterns are therefore not acceptable for DDNAME=:
  • 3-byte names that end with XX, meaning they are reserved as either current or future 
    CA Datacom®
     control areas.
  • 6-byte names that end with what could be a database ID from 001 through 999.
  • 7-byte names that end with what could be a database ID from 1000 through 9999.
    The DDNAME= value is verified for acceptability to protect you from unintentionally causing data corruption. The DDNAME check is the default but optional. You can prevent the DDNAME check by using a DBSIDPR parameter (DBUTLTY_EDIT_DATA_SET=) for individual MUF environments. However, we recommend that you allow the DDNAME check.
    The data corruption risk involves not the DDNAME itself but the content of the data set. For example, suppose that you used the CXX DDNAME as the output of a backup. You then copied the CXX DD statement and changed the DDNAME of the copy to be acceptable, avoiding the DDNAME= error. The backup would, however, then overlay the CXX data set, which is not the intent of a backup.
    If you specify an unacceptable name for DDNAME=, message DB10059E is generated. For more information about DB10059, see the  Messages page.
     We recommend that you allow DDNAME= check protection. You can, however, disable DDNAME= protection. To disable protection, assemble the DBSIDPR module used for this 
    CA Datacom®
     environment and specify NONE for the DBUTLTY_EDIT_DATA_SET= parameter. The default is DBUTLTY_EDIT_DATA_SET=FULL_1, which allows DDNAME= protection. 
  •  
    ,TABLE=
    Specifies the table in the database to which the records are to be added.
    •  
      Limits:
      DATACOM-NAME of the table in the database specified
    •  
      Default:
      (No default)
 
Optional Keywords
 
  •  
    ,MULTUSE=
    Specifies whether the add commands are to be directed to the MUF.
    •  
      YES
      MASSADD directs its input to the MUF. Direct commands to the MUF when adding records to a table defined with integrity constraints.
    •  
      NO
      MASSADD executes as a Single User job. In Single User mode, logging is not supported, and you do not have a log file to restart to ensure that the data and Index Areas are synchronized. Before using MASSADD, obtain a backup of the area in case you need to reload and try the function again.
    •  
      Limits:
      NO or YES
    •  
      Defaul:
      YES
    •  
      Dault:
      0
  •  
    ,OPTION2=  
    Specified special action to occur if a duplicate row is found, either return code 10 or return code 94(193).
    •  
      DUPS_IGN
      Causes duplicate rows to be counted and simply ignored.
    •  
      DUPS_DD
      Causes duplicate rows to be counted, written to an output data set with a DDNAME of DUPSTTT. The table name TTT is formatted the same as a DBUTLTY function EXTRACT and simply ignored.
    •  
      Limits:
       
DUPS_IGN, DUPS_DD
  •  
    Default:
     
No value
  •  
    ,STARTAFT=
     
Specifies a number of records to skip in the input data set before beginning to add records.
    •  
      Limits:
      Any 1- to 8-character integer
    •  
      Default:
       
0
  •  
    ,PRTY=
    Identifies for this execution the URT priority of frequent or long-running DB requests in the MUF issued by this DBUTLTY function.
    •  
      Limits
      :
      1 (lower) through 15 (higher)
      0 is allowed but means that you should use the default 16 value
    •  
      Default:
      16 is the default value if PRTY= is not specified or is set as 0
Example JCL (MASSADD)
The following example shows the command to add records to table TEL in database 400. The input data set is TELLER. In this example, the job defaults to an active MUF mode.
 
Note:
 Use the following example as a guide to prepare your JCL. The JCL statements are for example only. Lowercase letters in a statement indicate a value you must supply. Code all statements to your site and installation standards.
//jobname
See the previous note and JCL Requirements
.
// EXEC PGM=DBUTLTY,REGION=2M //STEPLIB
See the previous note and JCL Requirements
.
//TELLER DD DSN=input Input data set //SYSIN DD * Command Input MASSADD DBID=400,DDNAME=TELLER,TABLE=TEL /*
 
Sample Report
 
Following is a sample report page. For an example report header, see Sample Report Headers.
CONTROL CARD(S) .........1.........2.........3.........4.........5.........6.........7.........8 MASSADD DBID=400,DDNAME=TELLER,TABLE=TEL FUNCTION=MASSADD DBID=400 DDNAME=TELLER TABLE=TEL
This page of the report shows the following:
The command exactly as entered.
An analysis of keywords encountered and expected. Any errors found are flagged with a note in the left margin.
Any messages related to syntax processing.
RECORD ******1000 SUCCESSFULLY ADDED RECORD ******2001 SUCCESSFULLY ADDED RECORD ******3000 SUCCESSFULLY ADDED ADDED TEL 3,400
This page of the report shows the following:
 
RECORD
A line is produced for each 1,000 records successfully added.
 
ADDED
Report indicates that 3,400 Records were added to the table.