System Options under z/OS

UTILLOC= System Option: z/OS

Specifies location of certain types of temporary utility files.

Default:	WORK
Valid in:	configuration file, SAS invocation
Category:	File Control: SASFILES
PROC OPTIONS GROUP=	SASFILES
z/OS specifics:	valid values
See:	"UTILLOC= System Option" in SAS Language Reference: Dictionary

Syntax
Details
ALLOC Command Details
Diagnosing ALLOC Command Problems
Examples

Syntax

UTILLOC = "location" | ("location1", "location2", ...)

location

can be one of the following:

a UFS directory in the UNIX file system.
an ALLOC command that specifies the amount of space to be used for each utility file. For information about the syntax of the ALLOC command, see ALLOC Command Details.
the WORK library. The effect of specifying UTILLOC=WORK depends on whether the WORK library resides in a UFS directory or in a direct access bound library. If the WORK library resides in UFS, then UTILLOC=WORK causes certain temporary utility files to reside within temporary subdirectories of the WORK library directory. If the WORK library resides in a direct access bound library, then UTILLOC=WORK is equivalent to specifying an ALLOC command that provides the same maximum amount of space as that to which the current WORK library can be extended on its first (or only) volume. This default provides an adequate amount of space for most applications.

Details

The UTILLOC option specifies one or more locations for a new type of utility file that is introduced as part of the SAS 9 architecture. These utility files are comparable to SAS files with a type of UTILITY, but they are not members of the WORK library or any other SAS library. UTILLOC utility files are primarily used by applications that are enabled for multiple threads of execution.

Each location that is specified for the UTILLOC option identifies a single place at which utility files can be created. If multiple locations are specified, then the locations are used on a rotating basis by SAS applications as utility files are required. A location can be specified as a UFS directory or as an ALLOC command. An ALLOC command is not a location in the usual sense. Instead, it describes the operands that are used to create a temporary z/OS data set that will contain the utility file. Single quotation marks can be used in place of the double quotation marks that are shown in the syntax diagram.

When SAS uses a UFS location for a utility file, it first creates a temporary subdirectory that is subordinate to the specified location, and then creates the utility file in the temporary subdirectory. This temporary subdirectory and its contents are automatically deleted before the SAS session ends, provided that SAS ends normally. For information about removing temporary subdirectories that remain after a SAS session terminates abnormally, see The cleanwork Utility.

Each time SAS uses an ALLOC command for a utility file, SAS uses the operands that are specified as part of the ALLOC command to allocate a new temporary z/OS data set. This temporary data set receives a unique system-generated name, which allows multiple distinct utility files to be used at the same time. It is not possible to specify the data set name that is to be used for these temporary data sets.

For applications that use multiple utility files at the same time, specifying multiple locations that correspond to separate physical I/O devices might improve performance by reducing competition for device resources.

ALLOC Command Details

All of the following operands must be specified on the ALLOC command:

UNIT
TRACKS, CYL, or BLOCK(block length)
SPACE(primary[,secondary])

One or more of the following operands can be also specified on the ALLOC command:

UCOUNT(number of devices)
VOL(volser [,volser...])
STORCLASS(storage class)
MGMTCLAS(management class)
DATACLAS(data class)
DSNTYPE(LARGE)

The ALLOC command operands that are listed have the same syntax and meaning as when they are specified on the TSO ALLOCATE command. For more information, see the IBM documentation about the ALLOCATE command. An ALLOC command can be specified as a UTILLOC file location even in the batch environment. It is not necessary to have SAS running under TSO when you specify an ALLOC command as a utility file location. When you use an ALLOC command as a UTILLOC location, SAS recommends that you specify the UTILLOC command with a CONFIG file.

Certain SAS procedures can create a large number of separate utility files that are to be used at the same time. When a UTILLOC location is specified as an ALLOC command, each utility file resides in a separate, temporary z/OS data set, and the primary space amount will be allocated on disk for each utility file even if SAS needs to only write a small amount of data. SAS recommends that you specify a primary allocation amount that is modest in size. To increase the maximum amount of data that the utility files can contain, increase the secondary allocation amount or allow the utility files to extend to multiple volumes. SAS does not recommend specifying a large amount of primary allocation space.

To allow utility files to extend to multiple volumes, specify UCOUNT(n), where n is the maximum number of volumes, or use the DATACLAS operand to specify an SMS data class that designates a volume count greater than one. Specifying a list of volumes with the VOL operand is supported, but it is not recommended.

When you use multiple ALLOC command utility locations, the same space operands should be specified for each location because the UTILLOC locations are used on a rotating basis. The location that will be used for each utility file cannot be predicted in general, so it is best to specify the same maximum size for all utility files. Also, you can reduce competition for device resources by specifying multiple UTILLOC locations that include UNIT or STORCLAS operands that refer to different sets of disk devices. Contact the system programmer at your site for information about selecting the appropriate UNIT and STORCLAS operands to achieve the objective of reducing competition for device resources.

The temporary data sets that are created for utility files must be regular-format sequential data sets. Extended-format sequential data sets are not supported. Therefore, for the DATACLAS operand, do not specify a data class with a Data Set Name Type of extended.

Diagnosing ALLOC Command Problems

Problems that occur when processing utility files that are specified by an ALLOC command can be grouped into the following categories:

errors in the syntax of the ALLOC command. These problems include errors such as misspelling the name of an operand, failing to supply the required operands, and so forth.
failure of the system to perform the dynamic allocation requested by the ALLOC command. These problems can occur because the requested resources are not available or because names are specified that are not defined on the system.
insufficient space in the utility file. These problems occur when SAS is writing data to the utility file and the utility file becomes full, but the system is not able to allocate additional space to the utility file data set. The failure to allocate additional space can occur because no secondary space amount was specified, because the maximum number of extents have been allocated, or because no more disk space is available on the disk volume or volumes allocated to the utility file.

SAS does not detect problems with UTILLOC location specifications until an attempt is made to create a utility file.

The following example shows the type of message that is issued if the ALLOC command has a syntax error. In this case, the block length is omitted from the BLOCK operand. BLOCK(block length) should have been specified instead:

ERROR: Dynalloc syntax error: Unknown, or unsupported parm.
            Data set allocation request = ALLOC UNIT(DISK) UCOUNT(2) BLOCK SPACE(500,500) NEW DELETE
   ERROR: File allocation failure.
   ERROR: Utility file open failed.

In the following example the ALLOC command has valid syntax, but it refers to a unit name, BADUNIT, that is not defined on the system:

ERROR: Dynalloc SVC99 error: R15: 0X4, Reason: 0X21C, Info: 0                          
         Data set allocation request = ALLOC UNIT(BADUNIT) CYL SPACE(20,100) NEW DELETE
ERROR: File allocation failure.                                                        
ERROR: Utility file open failed.

In the following example no secondary space was specified, so SAS could not extend the utility file after the primary space amount was consumed:

Data set SYS08241.T093824.RA000.USERID.R0117125 could not be extended.
            Data set allocation request = ALLOC UNIT(DISK) UCOUNT(2) TRACKS SPACE(500) NEW DELETE
            Space used on volume (VIO)  = 500 tracks and 1 extents.
            Total space used = 500 tracks and 1 extents.
   ERROR: Unexpected error  Filename = SYS08241.T093824.RA000.USERID.R0117125.
   ERROR: No disk space is available for the write operation.  Filename = SYS08241.T093824.RA000.USERID.R0117125.

Note: The operands NEW and DELETE are shown as part of the dynamic allocation requests. These operands should not be specified as part of the ALLOC command because they are added automatically by SAS. [cautionend]

Examples

Here are some examples of the UTILLOC= system option:

UTILLOC='ALLOC UNIT(DISK) UCOUNT(2) CYL SPACE(20,100)'

```
UTILLOC='/tmp'
```

UTILLOC=('ALLOC UNIT(DISK) STORCLAS(POOL1) CYL SPACE(20,100)',
        'ALLOC UNIT(DISK) STORCLAS(POOL2) CYL SPACE(20,100)')

UTILLOC=("/dept/prod/utility1", "/dept/prod/utility2")

Top of Page