DSNPAT
The maximum total length that LOADPLUS allows for a data set name is 44 bytes. LOADPLUS removes any trailing blanks in the resolved pattern.
When invoking DSNUTILB, LOADPLUS includes this pattern in the TEMPLATE control statement that it builds for the IBM Db2 LOAD utility. Any variables that you include in your pattern for this type of load must be either valid for the IBM Db2 TEMPLATE control statement or translatable (as shown in the Symbolic variables for DSNPAT command option table) to a valid TEMPLATE variable. For more information about TEMPLATE control statements, see the documentation for the Db2 LOAD utility.
Specifying the default
You can specify the default for the DSNPAT command option in your installation options module by using the DSNPAT installation option. LOADPLUS was shipped with a different default value for each DDTYPE. The command option overrides the default that is in the installation options module.
'pattern'
Specify the pattern of variables and text, with surrounding single quotes, to use to create data set names.
The pattern that you specify in your DSNPAT option must allow LOADPLUS to generate unique data set names. If LOADPLUS encounters non-unique data set names, processing terminates. Note the following considerations:
- With multiple SORTOUT and SYSUT1 files, you must include the &DDNAME variable to generate unique names.
- For copy data sets, you might need to include additional variables, such as &VCAT, &DATEJ, or &TIME4 to generate unique names across multiple loads.
- If you plan to run concurrent LOADPLUS jobs or run multiple LOADPLUS steps in a worklist environment, we recommend that you include additional variables in the default pattern to ensure unique names. For example, the following value ensures that LOADPLUS generates unique names:
Variables
You can use any of the symbolic variables that are described in the Symbolic variables for DSNPAT command option table to construct your pattern. In addition, you can use text or provide user-defined variables from a user exit routine. For more information about these user exit routines, see the LOAD command option, DSNUEXIT, and LOADPLUS-user-exits.
Symbols for numeric variables (such as &DATE or &TIME) must be prefixed by a national character (alphabetic, #, @, or $). In the following example, the first statement causes an error, while the second is correct:
DSNPAT '&DB.&TS..RP&DATE'
Although you can prefix a symbolic variable with an alphabetic character, you cannot append characters. For example, XX&DB is valid, but &DBXX is invalid. &DB.XX is valid.
User-defined variables must begin with an underscore character, as in _DEPT. User-defined variables are not valid for a DSNUTILB load. For more information, see Rules-for-the-user-defined-variables-created-in-LOADPLUS-user-exits.
The following table describes the symbolic variables for DSNPAT command option:
Variable | Definition | Length of result | DSNUTILB load |
|---|---|---|---|
&DATE | Current date (in the format MMDDYY) | 6 bytes | Variable passed |
&DATEJ | Current Julian date (in the format YYYYDDD) | 7 bytes | Variable translated to the IBM &JDATE variable |
&DB | Database containing the space being used for this data set allocation | 8 bytes maximum | Variable passed |
&DDNAME | ddname being used for this data set allocation | 8 bytes maximum | Value passed |
&GRPNM | Db2 data sharing group name, or, in a non-data-sharing environment, the Db2 SSID | 4 bytes | Value passed |
&JDATE | Current Julian date (in the format YYDDD) | 5 bytes | Variable translated to the IBM &JDATE(3,5) variable |
&JOBNAME | JOB name used in the JCL | 8 bytes maximum | Variable passed |
&PART | Partition being used for this copy data set allocation You can use this variable for any data set. However, LOADPLUS substitutes the partition number only for copy data sets. For all other data sets, LOADPLUS substitutes the value 000. | 3 bytes for table spaces with 999 partitions or less 4 bytes for table spaces with 1000 through 4096 partitions | Variable passed |
&REPLACE | LOAD REPLACE being done (Y or N) | 1 byte | Job terminated |
&RESUME | LOAD RESUME being done (Y or N) | 1 byte | Job terminated |
&SSID | Db2 subsystem ID | 4 bytes | Variable passed |
&STEPNAME | STEP name used in the JCL LOADPLUS ignores PROC names. | 8 bytes maximum | Variable passed |
&TIME | Current time (in the format HHMMSS) | 6 bytes | Variable passed |
&TIME4 | Current time (in the format HHMM) | 4 bytes | Variable passed |
&TS | Table space containing the table specified in your LOAD command | 8 bytes maximum | Variable passed |
&USERID or &UID | Job user ID You must have a security package to use this variable. | 8 bytes maximum | Variable passed |
&UTIL 1 | BMC utility ID LOADPLUS truncates utility IDs longer than 8 bytes | 8 bytes maximum | Variable translated to the IBM &UTILID variable |
&UTILPFX 1 | BMC utility ID prefix | 8 bytes maximum | Value passed |
&UTILSFX 1 | BMC utility ID suffix | 8 bytes maximum | Value passed |
&VCAT | VCATNAME specified in the Db2 catalog for the table space that you are loading; or, if the table space is partitioned, the VCAT name from the first partition that you are loading | 8 bytes | Job terminated |
1 Utility IDs that include special characters might cause LOADPLUS to generate invalid data set names. For more information, see Utility ID variable.
Utility ID variable
If the utility ID has no special character delimiters, &UTILPFX contains the first eight bytes of text, and &UTILSFX contains the remaining eight bytes of text.
If the utility ID has a special character delimiter within the first eight bytes of text, &UTILPFX contains the bytes up to but not including the delimiter. &UTILSFX contains the eight bytes following the first delimiter. The first delimiter is not included in either variable. Any delimiter after the first is treated as normal text and might be included in &UTILSFX. Depending on the utility ID that is specified for this load job, &UTILSFX might be blank.
For example, if the utility ID is USER1/WORK1, the variables contain the following values:
&UTILPFX = USER1
&UTILSFX = WORK1
If the utility ID is USER1//WORK1, the variables contain the following values:
&UTILPFX = USER1
&UTILSFX = /WORK1
The following special delimiter characters tell LOADPLUS to split the utility ID:
Character | Description |
|---|---|
. | Period |
+ | Plus sign |
| | Bar |
; | Semicolon |
- | Dash |
/ | Slash |
¦ | Broken bar |
_ | Underscore |
: | Colon |
= | Equal sign |
Name construction
You can specify any or all nodes of a data set name by using variables or text. The following example generates data set names that contain the ID of the user, the table that is involved in the load, and the name of the load job:
The following example combines actual text with symbolic variables to generate a data set name:
In certain cases, a period is required in your pattern as a node delimiter or to indicate the end of a variable name. The following table illustrates concatenation in a data set name pattern and those instances in which a period is needed.
Variable concatenation examples
Task | Code | Result (where &UID=RDAB and _DEPT=DEV) |
|---|---|---|
Concatenate the values of 2 variables, with no node delimiter. | &UID_DEPT | RDABDEV |
Make 2 nodes from the values of 2 variables. | &UID._DEPT | RDAB.DEV |
Concatenate the value of a variable with text, no node delimiter. | &UID.NEW | RDABNEW |
Concatenate text with the value of a variable, no node delimiter. | NEW&UID | NEWRDAB |
Make 2 nodes from the value of a variable followed by text | &UID..NEW | RDAB.NEW |
Make 2 nodes from text followed by the value of a variable | NEW.&UID | NEW.RDAB |
LOADPLUS ignores trailing blanks and null value variables. Node-delimiting periods in the pattern, however, are included regardless of the variable’s value. This can result in an invalid data set name.
For example, given that &UID=RDAB and the value of _DEPT is null, the following pattern results in an invalid data set name of RDAB..NEW:
GDG names
For the following dynamically allocated data sets, you can also specify a pattern that contains a GDG name:
- Copy data sets
- SYSDISC files
- SYSERR files
- SYSMAP files
Each DDTYPE must have a different GDG base.
The GDG format that you use to construct data set names is the same as the one that you use in your JCL when allocating data sets with DD statements. Append the generation number in parentheses. The open parenthesis tells LOADPLUS that the pattern is a GDG name. The generation number can be an integer from 1 through 255.
If the base does not exist, LOADPLUS creates it for you, using everything in the pattern up to the open parenthesis as the base name. For more information, see Generating data set names.
The following example shows a valid GDG name:
If you use a substitution variable as the last variable before the open parenthesis, include a period before the open parenthesis, as in the following example:
For copy data sets, each partition must have a different GDG base if you specify COPYLVL PART on the LOAD command. To specify a pattern that includes a partition, the partition must not be in parentheses. The following example shows a valid name:
You cannot specify a pattern that contains a PDS name. The following example shows an invalid name:
'NONE' or ''
This value indicates that you do not want to use a pattern to create data set names for dynamic allocation. This option is valid only for DDTYPE SORTWORK.
You must enclose the keyword NONE with single quotes.