MASSADD (Add Records to Table)

The MASSADD function communicates with one MUF. Be aware of the following:
datacom150
The MASSADD function communicates with one MUF. Be aware of the following:
  • Ensure that DBUTLTY is communicating with the desired MUF by executing DBUTLTY with the same System Identifier module (DBSIDPR) that is being used by the MUF, and
  • 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 to be added in a single batch run during non-prime hours. You can 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 
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 and displays a message with a record count each time a checkpoint is taken. The function generates a User Requirements Table 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
The MASSADD function terminates with error message DB13037E identifying the record, a return code 10, and a small snap dump, if you attempt to add a record with a duplicate value for a key which is defined to be unique (see the chapter on using dumps in problem determination in for information on reading the snap dump). Transaction backout is not invoked when this condition is encountered. You can, however, execute the MASSADD function with the STARTAFT= parameter which allows you to specify a number of records to skip in the input data set.
Integrity Constraints
When executing through the MUF, the MASSADD function enforces any integrity constraints defined for a table.
The MASSADD function terminates with an error message, if you attempt to add a record which contains invalid data for any field which is defined in 
Datacom Datadictionary
 with DBEDITS=Y.
If any field in the table is defined in 
Datacom Datadictionary
 with 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. You must 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. Also, if the utility fails, a log file does not exist to be restarted to insure that the data and index are synchronized. If you do not use the MUF, back up the area before running the MASSADD function. This way 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 ◄ ─┬─┘ └─ NO ────┘ ►─┬─────────────────────────────┬────────────────────────────────────────────►◄ └─ ,STARTAFT= ─┬─ 0 ◄ ──────┬─┘ └─
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 database identifier for the database containing the table to which the records are being added.
    •  
      Valid Entries:
      DATACOM-ID of the database
    •  
      Default Value:
      (No default)
  •  
    ,DDNAME=
    Specifies the JCL DDname of the input data. If the input source is a VSAM file, 
    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 
    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 
    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 
     
    Datacom/DB
     Message Reference Guide.
     
     We recommend that you allow DDNAME= check protection. You can, however, disable DDNAME= protection. To disable protection, assemble the DBSIDPR module used for this 
    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.
    •  
      Valid Entries:
      DATACOM-NAME of the table in the database specified
    •  
      Default Value:
      (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.
    •  
      Valid Entries:
      NO or YES
    •  
      Default Value:
      YES
  •  
    ,STARTAFT=
    Specifies a number of records to skip in the input data set before beginning to add records.
    •  
      Valid Entries:
      Any 1- to 8-character integer
    •  
      Default Value:
      0
Example JCL (MASSADD)
The following 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.
 Use the following 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.