Considerations when unloading LOB or XML data to referenced files

In addition to the general considerations, the following considerations apply when unloading LOB or XML data to referenced files.

Linking referenced files to the output fields

To identify which LOB or XML data to unload to which referenced file, you specify the output descriptor name with the BLOBF, CLOBF, or DBCLOBF subtype of the CHAR or VARCHAR data type.

The following figure shows how the OUTPUT statements relate to the field specification.

Example OUTPUT statements and field specification for unloading to referenced files

   OUTPUT SYSREF1 DSNAME('/home/rdajdm/lobfr1')
     DSNTYPE(HFS)
   OUTPUT SYSREF2 DSNAME('RDAJDM.UNLOAD.LOBFR2')
     DSNTYPE(PDS) UNIT(SYSDA) SPACE(10,10) TRK DIR 50
   OUTPUT SYSREF3 DSNAME('RDAJDM.UNLOAD.XML')
     DSNTYPE(LIBRARY) UNIT(SYSDA) SPACE(50,50) CYL DIR 50

   SELECT *
   INTO
        NAME          CHAR(20),
        EXT           CHAR(3),
        AVI1          CHAR(30) CLOBF SYSREF1,
        AVI2          CHAR(30) CLOBF SYSREF2,
        AVI3          CHAR(30) CLOBF SYSREF3
   FROM RDAJDM.AVI
*

OUTPUT statement considerations

This section describes considerations regarding OUTPUT statements for referenced files.

Important

When unloading LOB or XML data, any SYSREC or SYSRED OUTPUT statements apply to unloading the base table only.

PDS and PDSE referenced files

The following considerations apply to OUTPUT options for PDS and PDSE referenced files:

You can use the VOLUMES option to specify the volume that you want UNLOAD PLUS to use. However, if you specify more than one volume, UNLOAD PLUS writes to only the first volume in the list.
If you include the &PART variable in a pattern for DSNAME, UNLOAD PLUS creates one data set for each partition of the base table space. If you do not include the &PART variable, UNLOAD PLUS creates a single data set.
The following OUTPUT options are incompatible:

Incompatible OUTPUT options for PDS and PDSE referenced files

Option	UNLOAD PLUS response
Any tape option	Terminates
DISKEXPD	Terminates
DISKRETN	Terminates
PCTPRIM	Ignores this option
MAXPRIM	Ignores this option
MAXSECD	Ignores this option
NBRSECD	Ignores this option
FILESZPCT	Ignores this option

HFS referenced files

For HFS referenced files, UNLOAD PLUS honors only the following OUTPUT options:

Descriptor name
DSNAME
DSNTYPE
SUBSETS

UNLOAD PLUS responds as follows to the other OUTPUT options:

If you specify any tape options, UNLOAD PLUS terminates.
UNLOAD PLUS ignores all other OUTPUT options.

The following information applies to specifying a pattern with the DSNAME option for HFS referenced files:

When you specify DIRECT YES, you can use patterns to have UNLOAD PLUS create additional subdirectories in your file system path. In the following example, the root portion of the path (/home/rdacxb) already exists and is the mount point for the file system. UNLOAD PLUS adds subdirectories to this path for the subsystem ID and partition number based on the two variables in the DSNAME pattern.
OUTPUT CLOB01 DSNAME('/home/rdacxb/&SSID/p&PART') DSNTYPE(HFS)
Important
When you specify DIRECT NO, specifying a pattern does not result in additional subdirectories in your file system path. UNLOAD PLUS terminates if it cannot find a file system path that uses the name that resolves from your pattern.
If you include the &PART variable, UNLOAD PLUS creates one HFS path subdirectory for each partition of the base table space.

Restrictions

The following restrictions apply to referenced output files:

You cannot unload XML data to referenced files defined as DBCLOB.
You cannot unload LOB data to referenced files of a different type (for example, you cannot unload CLOB data to a BLOB referenced file).
The number of data sets that UNLOAD PLUS will allocate for referenced files is limited to 256. If the options that you have specified cause UNLOAD PLUS to attempt to allocate more than 256 data sets, UNLOAD PLUS terminates.
The following restrictions apply when you specify DELETEFILES YES:
- When DIRECT NO is in effect, UNLOAD PLUS does not delete any referenced files.
- UNLOAD PLUS does not delete any HFS files. If UNLOAD PLUS abends when unloading to an HFS file, you must manually restore that file.

Additional considerations

The following additional considerations apply to referenced output files:

When DIRECT YES is in effect, you can unload your data to multiple referenced files. For additional information about using multiple referenced files, see Using referenced files.
UNLOAD PLUS unloads each XML document or LOB to a separate member (for a PDS or PDSE) or file (for an HFS).
UNLOAD PLUS generates HFS file names and PDS and PDSE member names as eight-byte names. The first character of the name is a letter and the remaining seven characters are alphanumeric characters.
When DIRECT YES is in effect, UNLOAD PLUS always creates a single, empty PDS or PDSE member to represent all rows that contain empty LOB and XML columns. UNLOAD PLUS creates this member regardless of the existence of an empty column.