Customizing Your SAS Session

Overview of Customization

Whether you are using interactive processing under TSO or batch processing, you might want to customize certain aspects of your SAS session. For example, you might want to change the line size or page size for your output, or you might want to see performance statistics for your SAS programs.
You can customize your SAS sessions by setting SAS system options that control SAS behavior. For more information about SAS system options, see System Options in the z/OS Environment.

Customizing Your SAS Session at Start Up

You can customize your SAS session in five ways:
  • Under TSO, pass operands into the SAS CLIST or SASRX exec that your site uses to invoke SAS. This method is usually used for one-time overrides of CLIST or SASRX exec operands. For more information about passing operands at SAS invocation, seeInvoking SAS under TSO: the SAS CLIST. Here are three examples:
    • sas options('nocenter linesize=80')
    • sasrx -options (nocenter linesize=80)
    • sasrx -nocenter -linesize 80
  • In batch mode, pass parameters into the SAS cataloged procedure that your site uses to invoke SAS. This method is usually used for one-time overrides of parameters in the cataloged procedure. For more information about passing parameters in batch mode, see Invoking SAS in Batch Mode: the SAS Cataloged Procedure. Here is an example:
    //MYJOB  EXEC SAS,
    //   OPTIONS='NOCENTER, LINESIZE=80'
  • Specify SAS system options in a user configuration file. This method is useful if you, as an individual user, always want to override the values of system options that are specified in your site's system configuration file. For more information about specifying SAS system options in a configuration file, see Configuration Files. The following examples use a TSO command to specify a user configuration file:
    sas  config('''my.config.file''')
    or
    sasrx  -config 'my.config.file'
    The following example specifies a user configuration file with JCL:
    //MYJOB  EXEC SAS,
    //      CONFIG='MY.CONFIG.FILE'
  • Execute SAS statements (such as OPTIONS, LIBNAME, and FILENAME statements) in an AUTOEXEC file. For more information, see Autoexec Files. This method is most useful for specifying options and allocating files that pertain to a particular SAS application.
  • In interactive mode, specify a SASUSER library that contains a user Profile catalog. For more information, see SASUSER Library.
For information about the order of precedence for options specified using these methods, Precedence for Option Specifications.

Configuration Files

Overview of Configuration Files

A configuration file contains SAS system options that are set automatically when you invoke SAS. SAS uses two types of configuration files:
  • the system configuration file, which is used by all users at your site by default. Your on-site SAS support personnel maintain the system configuration file for your site.
  • a user configuration file, which is generally used by an individual user or department.

Creating a User Configuration File

To create a user configuration file, use any text editor to write SAS system options into a physical file. The configuration file can be either a sequential data set or a member of a partitioned data set. It can have any record length, and either fixed length or variable length records. Embedded configuration files (those specified via the CONFIG= option inside a configuration file) can also be in a UFS directory.

Format of a Configuration File's Contents

Each line of a configuration file can contain one or more system options or comments. If you specify more than one system option on a line, use either a blank space or a comma to separate the options. If the file has the legacy configuration file format of LRECL=80 and RECFM=FB, then only columns 1-72 are used. The contents of columns 73-80 are ignored. If the file has any other format, then the entire line is used.
Two different types of comments are supported. If a line contains an asterisk in column one, then the entire line is a comment. If a comment of this type requires multiple lines, each line must begin with an asterisk. Comments beginning with /* and ending with */ can appear anywhere between option specifications, but cannot be imbedded within an option specification. Comments of this type can continue across line boundaries.
Note: An */ that ends a comment cannot be in column one. If it is in column one, it starts a separate comment for the entire line.
Some options can be on (enabled) or off (disabled). Specifying only the keyword enables the option, and specifying the keyword prefixed with NO disables the option. For example, a configuration file might contain the following option specifications to disable the options:
NOCENTER
NOSTIMER
NOSTATS
Options that take a value must be specified in the following way:
option-name=value
For example, a configuration file might contain the following lines:
LINESIZE=80
PAGESIZE=60
Note: When you specify SAS system options in a configuration file, blank spaces are not permitted before or after an equal sign.
A configuration file can contain the CONFIG= option. A CONFIG= option in a configuration file can name a single ddname, data set name, or UFS filename. It cannot name a list of config files. The contents of the named config file are logically inserted in place of the CONFIG= specification. If a CONFIG= option specifies a file that has already been read as a configuration file, a warning message is written to the log and the file is not read again during this session.
The configuration file is processed as if all of the lines (other than comments) were concatenated into a single string with one blank space separating the lines, which means that options whose value can contain blank spaces can be continued across line boundaries. For example, the specification of the option in the following example is on five separate lines, but it would be processed as if it is on one line:
jreoptions=(
   -jreoption1
   -jreoption2
   -jreoption3
  )
In cases where separating concatenated lines with a blank space is not suitable, two alternative methods of explicit concatenation are provided.
  • If the file has the legacy format, and there is a non-blank character in column 72, then the next line is concatenated without an intervening blank space. The character in column 72 is not ignored, it is included in the concatenated value.
  • If the legacy method of explicit concatenation does not apply, and the last non-blank character of the line (or of columns 1-71 in a legacy format file) is a hyphen (-), then the hyphen is deleted and the next non-comment line is concatenated without an intervening blank space. If the last non-blank character is a plus sign (+), then the next non-comment line is concatenated without an intervening blank space. Any leading blank spaces of that line are also removed.
For example, the following option specification is invalid because a blank space is inserted between the equal sign and the value.
YEARCUTOFF=
1950
The following option specification is valid because the value is concatenated immediately following the equal sign, and a blank space is not inserted.
YEARCUTOFF=+
1950
Option values in SAS configuration files can contain symbolic references. The values of these symbolic references are resolved from a variable that is set in the TKMVSENV file. For example, the localized member of the default configuration file concatenation contains a statement similar to the following:
SASHELP='MVS:&HLQ..ENW0.SASHELP'
In this option value, &HLQ. is a variable symbol. The variable HLQ is assigned a value in the TKMVSENV file, in a statement similar to the following:
set HLQ=<high-level-qualifier>
where "<high-level-qualifier>" is your actual high-level-qualifier for SAS that is set at install time. Therefore, the final value of the SASHELP option is resolved as the following:
SASHELP=’<high-level-qualifier>.ENW0.SASHELP’

Specifying a User Configuration File

To tell SAS where to find your user configuration file, do the following:
  • If you use the SAS CLIST or SASRX exec to invoke SAS under TSO, use the CONFIG operand - for example:
    sas config('''my.config.file''')
    or
    sasrx -config 'my.config.file'
  • If you use the SAS cataloged procedure to invoke SAS in batch mode, use the CONFIG= parameter - for example:
    //S1  EXEC SAS,CONFIG='MY.CONFIG.FILE'
The user configuration file that you specify is executed along with the system configuration file that your installation uses. This happens because the SAS CLIST, the SASRX exec, or the SAS cataloged procedure concatenates the file that you specified to the system configuration file.
During initialization, the specified value of the CONFIG= option is replaced with the list of all configuration files that are actually processed. PROC OPTIONS displays this new value.
Note: SAS system options that you specify in the user configuration file override system options that are specified in the system configuration file.

Autoexec Files

Overview of Autoexec Files

Under z/OS, an autoexec file can be a sequential data set, a member of a partitioned data set, or a UFS file. Unlike configuration files, which contain SAS system options, an autoexec file contains SAS statements. These statements are executed immediately after SAS has been fully initialized and before any SAS input source statements have been processed. For example, an autoexec file could contain the following lines:
options fullstats pagesize=60 linesize=80;
libname mylib 'userid.my.lib';
dm 'clock';
The OPTIONS statement sets some SAS system options, the LIBNAME statement assigns a library, and the DM statement executes a command.
Note: Some SAS system options can be specified only when you invoke SAS. These system options cannot be specified in an OPTIONS statement. Therefore, they cannot be specified in an autoexec file. For information about SAS system options and where they can be specified, see Summary Table of SAS System Options Available under z/OS.

Displaying Autoexec Statements in the SAS Log

SAS statements that are submitted from an autoexec file usually are not displayed in the SAS log. However, if you specify the ECHOAUTO system option when you invoke SAS, then SAS writes (or "echoes") the autoexec statements to the SAS log as they are executed.

Using an Autoexec File under TSO

Under TSO, use the AUTOEXEC operand when you invoke SAS to tell SAS where to find your autoexec file. For example, the following command invokes SAS and tells SAS to use an autoexec file named MY.EXEC.FILE:
sas autoexec('''my.exec.file''')

Using an Autoexec File in Batch Mode

To specify an autoexec file in a batch job, use a JCL DD statement to assign the ddname SASEXEC to your autoexec file. This DD statement must follow the JCL EXEC statement that invokes the SAS cataloged procedure. For example, the following two lines of JCL can be used to accomplish the same results in a batch job as the previous example did under TSO:
//MYJOB    EXEC SAS
//SASEXEC  DD DSN=MY.EXEC.FILE,DISP=SHR

Concatenating Autoexec Files

You can concatenate multiple AUTOEXEC files in the ddname that is the value of the AUTOEXEC system option. Under TSO, you can list multiple AUTOEXEC files on the REXX or CLIST AUTOEXEC command-line option:
autoexec("autoexec1.sas autoexec2.sas")
The REXX or CLIST then allocates these data sets to the SASEXEC ddname.
You can also concatenate AUTOEXEC files with the APPEND and INSERT system options if all of the files are UFS files:
autoexec='~/autoexec2.sas' insert=(autoexec='~/autoexec1.sas'
If you use the INSERT option, the file is prepended to the existing autoexec file.
If any file in a concatenated autoexec list does not exist or cannot be opened (for example, if you are not authorized for read access), then SAS issues error messages to the log that indicates system start-up failure. SAS terminates without executing any of the files in the autoexec concatenation list.

SASUSER Library

Overview of the SASUSER Library

SAS enables you to customize certain features while your SAS session is running and to save these changes. The SASUSER library contains various SAS files in which SAS records these settings. For example, in Base SAS software, any changes that you make to function key settings or to window attributes are stored in a catalog named SASUSER.PROFILE. The SASUSER library can also contain personal catalogs for other SAS software products. You can also store SAS data files, SAS data views, SAS programs, SAS/ACCESS descriptor files, and additional SAS catalogs in your SASUSER library. In addition to storing function key settings and window attributes, the SASUSER.PROFILE catalog is used to store your DEFAULT.FORM. The DEFAULT.FORM is created by the FORM subsystem. It is used to control the default destination of all output that is generated by the PRINT command. For information about the FORM subsystem, see Using the PRINT Command and the FORM Subsystem and the SAS System Options: Reference.
You can use three methods to set up your SASUSER library:
  • Establish a permanent SASUSER library that is accessed for read and update. This method is how SASUSER must be set up if you want settings that are modified in the current SAS session to be in effect for a subsequent SAS session, which is the typical arrangement when you run SAS interactively. Creating a permanent SASUSER library is also necessary if you intend to save other application files in the SASUSER library for use in a later session. When accessing a permanent SASUSER library for read and update, only one SAS session at a time can use the SASUSER library. To access a personal SASUSER library for read and update, leave the SASUSER option unspecified and allocate the ddname SASUSER to the SASUSER library. The SAS CLIST and SASRX exec that are supplied by SAS to invoke SAS under TSO work this way by default. They also create the SASUSER library data set if it does not exist. The default data set name that they use is <prefix>.SAS9.SASUSER, where <prefix> is the system prefix that is defined in your user profile, or with your user ID if no prefix is defined.
  • Establish a permanent SASUSER library that is enabled for read access only. This method enables you to create a single SASUSER library that is shared by multiple SAS sessions that are running simultaneously. This method also enables you to provide other users with a SASUSER library that contains a set of pre-configured settings that are protected from write access via system authorization facilities (for a bound library) or via UFS permissions (for a UFS library). To access a SASUSER library in either a shared or read-only manner, you must specify the RSASUSER option. For more information about RSASUSER, see “RSASUSER System Option” in the SAS System Options: Reference.
  • Establish a temporary SASUSER library that exists only for the lifetime of the current session. This method is appropriate for applications that can use the default settings and that do not need to save settings. If you do not specify the SASUSER option and do not allocate the SASUSER ddname, then SAS uses this method in the batch environment by default. You can also run interactive sessions in this manner by specifying the SASRX option NOSASUSER. When you do not specify a SASUSER library, SAS creates a new PROFILE catalog that is used to store profile information for use during the current SAS session. This catalog is placed in the WORK library, and a note to this effect is written to the SAS log. The WORK library is typically deleted at the end of your session, which means that any changes made to the PROFILE catalog will not be available in a subsequent SAS session.
If you are running SAS under TSO and you want to specify SASUSER in your SAS config file, then you need to specify the SASRX option NOSASUSER to prevent SASRX from allocating the SASUSER library before the config file is processed. This specification is available only if you are using SASRX. It is not available if you are using the CLIST because the CLIST does not have the NOSASUSER option.

Creating Your Own SASUSER Libraries

By creating your own SASUSER libraries, you can customize SAS software to meet the requirements of a number of different types of jobs. For example, suppose you want to create a user profile for a particular type of task that requires a unique set of key definitions.
To create this user profile, you must first create a SAS library that can be used as the SASUSER library. The easiest way to create this library is to start a SAS session and then use a LIBNAME statement to create the library, as explained in Assigning SAS Libraries Internally . For example, to create a SAS library with a physical filename of ABC.MY.SASUSER, submit the following LIBNAME statement:
libname newlib 'abc.my.sasuser' disp=new;
Notice that a libref of NEWLIB was used in this example. SASUSER is a reserved libref and cannot be reassigned during a SAS session.
You can also use the TSO ALLOCATE command to create a physical file for use as your SASUSER library. By using the ALLOCATE command, you can avoid using the LIBNAME statement. However, to use the ALLOCATE command effectively, you must be familiar with TSO commands and with DCB (data control block) attributes. Here is a typical ALLOCATE command for the SASUSER library that provides satisfactory performance at many sites:
alloc fi(newlib) da('abc.my.sasuser') new
      catalog space(80 20) dsorg(ps) recfm(f s)
      blksize(6144) reu
When you enter this ALLOCATE command from the READY prompt, a physical file named ABC.MY.SASUSER is created with the correct attributes for a SAS library.
To use the new SAS library as the SASUSER library, you must end your SAS session and start a second session. When you start a second session, you can use the SASUSER option of the SAS CLIST or SASRX exec to specify ABC.MY.SASUSER as the SASUSER library.

Specifying Your Own SASUSER Library

After creating your own permanent SAS library, designate that library as your SASUSER library. You can do this in either of the following ways:
  • Use the SASUSER option of the SAS CLIST or SASRX exec to specify the physical filename of your SAS library. For example, if you create a library with a name of ABC.MY.SASUSER, then you use the following CLIST command to invoke SAS:
    sas sasuser('''abc.my.sasuser''')
    Or, you would use the following SASRX command to invoke SAS:
    sasrx -sasuser 'abc.my.sasuser'
    When you enter this command, the libref SASUSER is associated with the SAS library whose physical filename is ABC.MY.SASUSER. Any profile changes that you make during your session are saved in the SAS catalog SASUSER.PROFILE, which is a member of the SASUSER library. These changes will be retained when you end your SAS session.
  • Use the SASUSER= system option to specify the ddname that identifies your SAS library. For more information, see SASUSER= System Option: z/OS.
Both of these methods require that you identify the SAS library when you invoke SAS; you cannot change the SASUSER library during a SAS session.

SAS System Options

Overview of SAS System Options

SAS system options control many aspects of your SAS session, including output destinations, the efficiency of program execution, and the attributes of SAS files and libraries.
After a system option is set, it affects all subsequent DATA and PROC steps in a process until it is specified again with a different value. For example, the CENTER|NOCENTER option affects all output from a process, regardless of the number of steps in the process.

Specifying or Changing System Option Settings

The default values for SAS system options are appropriate for many of your SAS programs. If you need to specify or change the value of a system option, you can do so in the following ways:
  • Create a user configuration file to specify values for the SAS system options whose default values you want to override. For more information, see Creating a User Configuration File.
  • Under TSO, specify any SAS system option following the OPTIONS parameter in the SAS CLIST command:
    sas options('option-list')
    For options that can be on or off, just list the keyword that corresponds to the appropriate setting. For options that take a value, list the keyword identifying the option followed by an equal sign and the option value, as in the following example:
    sas options('nodate config=myconfig')
    For detailed information about the SASRX exec, see Starting SAS with SASRX.
  • In batch mode, specify any SAS system option in the EXEC SAS statement:
    // EXEC SAS,OPTIONS='option-list'
    For example:
    // EXEC SAS,OPTIONS='OPLIST LS=80 NOSTATS'
  • Specify SAS system options in an OPTIONS statement in an autoexec file. This file is executed when you invoke SAS, or in an OPTIONS statement at any point during a SAS session. Options specified in an OPTIONS statement apply to the process in which they are specified. They are reset for the duration of the SAS session or until you change them with another OPTIONS statement.
    For example:
    options nodate linesize=72;
    To find out whether a particular option can be specified in the OPTIONS statement, see Summary Table of SAS System Options Available under z/OS. For more information about autoexec files, see Autoexec Files. For more information about the OPTIONS statement, see SAS System Options: Reference and Step-by-Step Programming with Base SAS Software.
  • Change SAS system options from within the OPTIONS window. On a command line, enter the keyword OPTIONS. The OPTIONS window appears. Place the cursor on any option setting and type over the existing value. The value is saved for the duration of the SAS session only. Not all options are listed in the OPTIONS window. For more information, see OPTIONS Window.
  • Specify PROC OPTLOAD or the DMOPTLOAD command to load a set of options that you have saved in a file or data set by using PROC OPTSAVE or the DMOPTSAVE command. For example, specifying
    proc optload data=options1;
    run;
    loads the set of options that you have saved in a file named options1. You can save multiple sets of options, and then use the OPTLOAD procedure to load any of your sets of options at any time during a SAS session. The ability to load the options at any time during a SAS session provides advantages over using a configuration file, which you can use only when you invoke SAS. However, not all options are saved by PROC OPTSAVE. For information about which options cannot be saved with PROC OPTSAVE, see “The OPTSAVE Procedure” in Base SAS Procedures Guide.

Determining How an Option Was Set

Because of the relationship between some SAS system options, SAS might modify an option's value. This modification might change your results.
To determine how an option was set, enter the following code in the SAS Program Editor:
proc options option=option value; run;
After you submit this code, the SAS log will display the value that was set for the option, and how the value was set. For example, the following log message is displayed when you enter
proc options option=CATCACHE value; run;
Results of the OPTIONS Procedure for the CATCACHE Option
Option Value Information for SAS Option CATCACHE
      Option Value:  0
      Option Scope:  NoReb
      How option value was set:  Shipped Default
Contact your on-site SAS support personnel for more information.

Default Options Table and Restricted Options Table

Your on-site SAS support personnel might have created a default options table or a restricted options table. Information about creating and maintaining these tables is provided in the configuration guide for SAS software in the z/OS environment.
The default options table is created by your site administrator and provides a global set of defaults that are specific to your site. It reduces the need to duplicate options in every system config file at your site.
The restricted options table is created by your site administrator. It specifies option values that are established at start-up and cannot be overridden. If an option is listed in the restricted options table, any attempt to set it is ignored. An attempt to set it with the options statement causes a warning message to be written to the log. For example
1    options vsamload;
             --------
             36
WARNING 36-12: SAS option VSAMLOAD is restricted by your Site Administrator and
cannot be updated.
To find out which options are in the restricted options table, submit this statement:
PROC OPTIONS RESTRICT;
RUN;
For a list of restricted options, see “Restricted Options” in SAS System Options: Reference.
Some SAS system options cannot be added to a restricted options table. To find out whether an option can be restricted, run PROC OPTIONS with the DEFINE option. For example:
PROC OPTIONS OPTION=option-name DEFINE;
RUN;
The output that is returned by the preceding statement will include either of the following messages:
Your Site Administrator can restrict modification of this option.
or
Your Site Administrator cannot restrict modification of this option.
If an ineligible option has been placed in the restricted options table, the following message is issued:
SAS option option-name cannot be restricted by your Systems Administrator.
SAS terminates with an abend. If you receive such an error, you should immediately notify your site administrator.

Displaying System Option Settings

To display the current settings of SAS system options, use the OPTIONS procedure or the OPTIONS window.
Some options might seem to have default values even though the default value listed in Summary Table of SAS System Options Available under z/OS is none. This situation happens when the option is set in a system configuration file, in the default options table, or in the restricted options table.
You can use the VALUE parameter of the OPTIONS procedure to see when an option's value was set.

OPTIONS Procedure

The OPTIONS procedure writes system options that are available under z/OS to the SAS log. By default, the procedure lists one option per line with a brief explanation of what the option does. To list the options with no explanation, use the SHORT option:
proc options short;
run;
To list all the options in a certain category, use the GROUP= option:
proc options group=sort;
run;
Some options, such as system options that are specific to SAS/ACCESS interfaces or to the SAS interface to ISPF, are listed only if you specify the GROUP= option. For more information, see OPTIONS Procedure: z/OS.

OPTIONS Window

To display the OPTIONS window, enter OPTIONS on a command line. The OPTIONS window displays the settings of many SAS system options.

Precedence for Option Specifications

When the same option is set in more than one place, the order of precedence is as follows:
  1. restricted options table, if there is one
  2. OPTIONS statement or OPTIONS window
  3. SAS invocation, including invocation by way of an EXEC SAS JCL statement (in batch) or by way of the SAS CLIST or SASRX exec commands (under TSO)
  4. user configuration file, if there is one
  5. system configuration file (as SAS software is initialized)
  6. default options table, if there is one
For example, options that you specify during your SAS session (using the OPTIONS statement or OPTIONS window) take precedence over options that you specified when you invoked SAS. Options that you specify with the SAS CLIST or SASRX exec commands take precedence over settings in the configuration file. The settings in the user configuration file take precedence over settings in the system configuration file and in the default options table.
Note: Options that are specified in the restricted options table can be updated only by your SAS administrator.