Load function

Initializes a database and loads it from an input data file.

The Load function initializes a database and loads it from an input data file. It can be used for initial loading of a database, as part of a database reorganization, or for reloading a database after changing the DBD definition.

Warning: The Load function automatically performs a Zeroload. Zeroloading an existing database re-initializes the database and all data is lost.

Syntax - Command Line

mfims imsdbu LOAD {database-name|filename}
     [[NO]CLS] 
     [[NO]COMPRESS[(program)]]
     [DATA(position)]
     [DSN(filespec)]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [LAYOUT(type)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [LRECL(length)]
     [PROGRESS(no-of-segments)]
     [RECFM(format)]
     [[NO]SEGEXIT[(program)]]
     [SEGM(position)]

Syntax - JCL

//LOAD     EXEC PGM=MFDBUJCL,PARM='LOAD,database-name,{dataset-name | catalog-name}'
//SYSOUT   DD  SYSOUT=*
//INPUT    DD  DSN=input-dataset,DISP=SHR

Parameters - Command Line

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
DATA
Specifies the starting position of the segment data in the data record.
Default: DATA(9)
Sub-parameter
position The starting position of the segment data within the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. Use the DATA directive only when LAYOUT(G) is specified.
  3. DATA is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  4. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment data is the first field following the segment name which follows the LL field in a variable length file, specify 9 for the DATA value.
General Rules
When loading GSAM files, the DATA value is ignored.
DSN
Specifies the dataset name of the input file containing the segment data.
Default: DSN(*.DBU)
Sub-parameter
filespec The dataset name of the input file containing the segment data.
Syntax Rules
  1. If you specify the base name of filespec as an asterisk (*) it is replaced by the DBD name.
  2. Use unique extensions for the input file names. This is enforced even if the database data files are in a different directory than the input file.
  3. The input dataset resides in the current directory unless you specify a drive and/or directory.
  4. The input file name, not including the drive and directory, must not be the same as the name of the files for the database. For example, the data files for a database named MYDBD would be MYDBD.DAT and MYDBD.IDX, and the input file name cannot be either of these file names.
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value Category Example Cause
4 General warning message A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 IMS specific warning message A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 General severe error An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 IMS Option specific severe error An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 Severe error - possible temporary condition A temporary I/O error such as a 'file locked' or 'database locked' status.
16 Severe error- permanent - likely installation problem A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 Severe error - permanent An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
    PROGRESS(1000)
    ;use local log
    LOG(C:\MYDIR\MYDB.LOG)
LAYOUT
Specifies the type of the input or output file.
Default: LAYOUT(D)
Sub-parameter
type The type of input file. One of:
D
The input file is an IMSDBU file layout. No additional directives are required to describe the input file.
G
The input file is a generic layout. Additional directives are required to describe the input file and its contents.
I
The input file is an IBM format. No additional directives are required to describe the input file.
S
The input file is a sequential file. Additional directives are required to describe the input file and its contents.
Syntax Rules
  1. The additional directives required for the G and S parameters are RECFM, LRECL, SEGM, and DATA.
General Rules
  1. LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
LRECL
Specifies the length for fixed length generic layout input records.
Default: LRECL(0)
Sub-parameter
length The length for fixed length generic layout input records.
Syntax Rules
  1. LRECL is required when loading from a fixed-length generic file; that is, when LAYOUT(G) is specified.
  2. LRECL is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.
RECFM
Specifies the format of the input or output records.
Default: RECFM(V)
Sub-parameter
format The format of the input records. One of:
V
Records are variable length. With LAYOUT(G), each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility. With LAYOUT(S), files are in Micro Focus record sequential format.
F
Records are a fixed length. Requires
Syntax Rules
  1. Use RECFM only when LAYOUT(G) or LAYOUT(S) is specified.
  2. RECFM is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
  3. When format is set to V and LAYOUT(G) is specified, each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility.
  4. When format is set to V and LAYOUT(S) is specified, files are in Micro Focus record sequential format.
  5. When format is set to F, you must also specify LRECL to provide the record length.
SEGEXIT
Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add process.
Default: NOSEGEXIT
Sub-parameter
program The name of the exit program to use.
Syntax Rules
  1. NOSEGEXIT disables this exit.
SEGM
Specifies the starting position of the 8-byte segment name in the data record.
Default: SEGM(1)
Sub-parameter
position The starting position of the 8-byte segment name in the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. Use the SEGM directive only when LAYOUT(G) is specified.
  3. SEGM is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  4. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment name is the first field following the LL field in a variable length file, specify 1 for the SEGM value.
General Rules
  1. When loading GSAM files, the SEGM value is ignored.
  2. When loading Fast Path databases which use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.

Parameters - JCL

database-name
The name of a database on which the function operates.
dataset-name
Dataset name of the data to be loaded.
catalog-name
If the dataset containing the data to be loaded is in the JCL catalog, then you can specify the catalog name instead of the dataset name.
input-dataset
The dataset containing input data.

Inputs

There are a variety of input file formats supported for loading databases.

The database to be loaded must be a primary physical DBD or GSAM DBD which has been defined using DBDGEN. An automatic Zeroload is performed for physical databases. GSAM databases do not require the Zeroload step. A Load is not required, and should not be run, for any other kinds of databases. An error message results if you attempt to Load one of the following databases:

  • The primary index for a HIDAM database. A primary index database is not required. The .IDX component of an MFIMS database is the equivalent of this index and is created automatically when loading the primary database.
  • Secondary index databases. These are created automatically when loading the primary database they index. A secondary index DBD which defines non-unique keys must be Genned prior to performing a Load for the primary database. When loading a database which contains segment data, any 'user data' in the index will be lost.
  • Databases defined as ACCESS=LOGICAL. The physical databases contain the required pointers to support logical relationships.

Exclusive use databases can be loaded. IMSDBU does not support loading of User Exit databases. The DBUTIL utility can be used for loading User Exit databases.

Outputs

The database data files are created and loaded by this function. Any secondary index databases are also created and loaded. If the database contains logical children definitions, the PtrUpdate function must be run before the database can be accessed by an application program.

Logically Related Databases

Loading logically related databases requires multiple steps that must be performed in a fixed sequence. In most cases, this involves multiple databases. The Makelist function can assist in creating the steps required to load a set of logically related databases.

The Load function performs a physical load of the segment data. The Load function does not process logical relationships. Logical children are connected to their logical parents by the PtrUpdate function. PtrUpdate also connects or establishes paired logical child relationships. A database that contains logical children segments cannot be accessed by an application until the PtrUpdate completes.