• Article History
• RSS Feed
• Mark as New
• Mark as Read
• Bookmark
• Subscribe
• Printer Friendly Page
• Report Inappropriate Content

Restricted options in SAS are system options for the programming run-time whose values are set globally by the site administrator and cannot be overridden.

They are a feature of SAS® Viya®, SAS® 9.4 and SAS® Viya® 3.5, and I'm sure they were a feature in earlier releases of SAS software too. When a SAS option is set by an administrator in the sas.compute.server: restricted_options configuration instance for the SAS Viya Compute Service, users cannot change that SAS option in their SAS programs. They work for SAS Connect and Batch servers too.

Restricted options don't get much attention, and they are not new. However, I think there are use cases for them. This short post aims to remind you they exist and suggest a couple of ways SAS administrators might find them useful.

Set restricted options for the compute server using SAS Environment Manager

To demonstrate, let's choose two SAS options which take values (EMAILHOST and EMAILPORT) and one ( NOMPRINT) for which either the option name or its inverse is set. Options like this and their inverse are mutually exclusive and the inverse is prefixed with 'NO', e.g. NOMPRINT is the inverse of MPRINT, and NOFULLSTIMER is the inverse of FULLSTIMER.

SAS Help Center has a Dictionary of System Options, and a separate list of System Options for Macros.

Set restricted options for all compute sessions in the sas.compute.server: restricted_options configuration instance, which you can find in SAS Environment Manager, on the Configuration page in the 'All services' view if you search for Compute Service. Alternatively, you can find the same thing if you switch to the 'Definitions' view, and search for sas.compute.server (which is confusingly what configuration definitions for the SAS Compute Service are listed under). In that view, the configuration instance is labelled Compute Service: restricted_options. Whichever of those ways you find it, it is the same configuration instance.

The restricted options in this demonstration are:

-emailsys=smtp
-emailhost=our.correct.mailhost.com
-emailport=587
-NOMPRINT

Each SAS option is prefixed with a dash or minus sign. It is a good practice to put each option on a separate line as shown above, to be more readable.

An equals sign is used between the option name and value where the option takes a value.

String values do not appear to need to be quoted, though I tried emailhost without quotes around the hostname, as well as with both single and double quotation marks around the hostname ('our.correct.mailhost.com', not our real SMTP server hostname), and it worked fine in all three cases. Putting single or double quotes around the value for emailport, which expects a numeric value, caused my next compute session to fail to start, with a message in the sas-compute-server pod logs saying ERROR: Invalid option value '587' for SAS option EMAILPORT.

Here is what this looks like in SAS Environment Manager, in the contents textbox of the sas.compute.server: restricted_options configuration instance:

01_DS_Setting_restricted_options_in_SAS_Environment_Manager.png

Setting restricted options for the SAS Compute Service in SAS Environment Manager

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

As you can see in the screenshot above, I tried putting two options on the same line. It worked, though it is less easy to read and for that reason I don't recommend you do this.

See what happens if users try to modify restricted options in their code

With the Compute Server restricted_options set as shown in the screenshot above, I started a new compute session in SAS Studio (hint: Options > Reset SAS Session is a quick way to do this if SAS Studio is already open and you already have a compute session running). Then I tried running this, which attempts to update the value of those SAS options:

options emailhost=spam.mailhost.com
 emailport=25
 mprint;

The log output contains warnings explaining that you cannot update those options because they are restricted:

79 
80 options emailhost=spam.mailhost.com
 ---------
 36
WARNING 36-12: SAS option EMAILHOST is restricted by your Site Administrator and cannot be updated.
81 emailport=25
 ---------
 36
WARNING 36-12: SAS option EMAILPORT is restricted by your Site Administrator and cannot be updated.
82 mprint;
 ------
 36
WARNING 36-12: SAS option MPRINT is restricted by your Site Administrator and cannot be updated.
83

Remove restricted options and try again

Then I used SAS Environment Manager as above, and removed the lines we added previously from the sas.compute.server: restricted_options configuration instance. After resetting my SAS session again, running the same statement in SAS Studio works, there is nothing much to see in the log output, this time it just works:

79 
80 options emailhost=spam.mailhost.com
81 emailport=25
82 mprint;
83

Having run the code above successfully, we can run this to check the new values of these three options were set successfully:

proc options option=(emailhost emailport mprint);
run;

Here is the log output from that statement:

79 
80 proc options option=(emailhost emailport mprint);
81 run;
 SAS (r) Proprietary Software Release V.04.00 TS1M0
 EMAILHOST=spam.mailhost.com
 Specifies one or more domain names for SMTP e-mail servers.
 EMAILPORT=25 Specifies the port number for the SMTP e-mail server that is specified in the EMAILHOST option.
 MPRINT Displays the SAS statements that are generated by macro execution.
NOTE: PROCEDURE OPTIONS used (Total process time):
 real time 0.00 seconds
 cpu time 0.00 seconds
 
82

These values can now be successfully changed by the end user since they are no longer restricted.

That's about all there is to it, for a demonstration using the SAS Compute Server. There are similar restricted_options configuration instances for SAS/Connect Spawner (sas.connect.server: restricted_options) and the SAS Batch Service (sas.batch.server: restricted_options). They work much the same way.

Modify restricted_options from the command line

Configuration instances, including these ones, can be modified using the SAS Viya Command-line Interface (CLI) too. We have to do a little bit of JSON gymnastics with jq, but with help or an example to crib from, it isn't too bad. Here is an example script that adds -NOMLOGIC to the compute server restricted options:

#!/bin/bash
# Line to add to Compute Server restricted_options
new_ro_line="-NOMLOGIC"
# Create timestamp
_currentTimeStamp=$(date "+%Y%m%d-%H%M%S")
# Define filenames which are unlikely to clash
orig_json=/tmp/compute_restricted_options_config_orig_${_currentTimeStamp}.json
orig_ro_content=/tmp/compute_restricted_options_content_orig_${_currentTimeStamp}.txt
mod_ro_content=/tmp/compute_restricted_options_content_modified_${_currentTimeStamp}.txt
mod_ro_content_json=/tmp/compute_restricted_options_content_modified_${_currentTimeStamp}.json
mod_json=/tmp/compute_restricted_options_config_modified_${_currentTimeStamp}.json
# Extract the configuration
echo "Download current Compute Service restricted_options configuration"
sas-viya configuration configurations download \
 --definition-name sas.compute.server \
 --service compute \
 | jq -r 'del( .links) | del(.items[] | select(.name!="restricted_options")) | del(.items[].links) | .count = 1' \
 > $orig_json
# Get the content part of the configuration and modify it, adding the new_ro_line at the end of the existing content
echo "Modify Compute Service restricted_options content"
jq -r '.items[0].contents' $orig_json > $orig_ro_content
cp $orig_ro_content $mod_ro_content
echo $new_ro_line >> $mod_ro_content
jq -sR . $mod_ro_content > $mod_ro_content_json
# Replace the content part of the configuration with the modified version in the JSON file
jq -r --slurpfile newcontents $mod_ro_content_json \
 '.items[0].contents=$newcontents[]' $orig_json \
 > $mod_json
# Apply the configuration
echo "Apply new Compute Service restricted_options configuration"
sas-viya configuration configurations update --file $mod_json
# Cleanup
rm $orig_json $orig_ro_content $mod_ro_content $mod_ro_content_json $mod_json

This bash script uses the sas-viya CLI, and its configurations plugin, and it assumes you are authenticated as a SAS Administrator. It also uses one of my favorite tools for SAS Viya administration tasks from the command line, jq.

The key steps are:

1. Download the configuration instance JSON, and use jq to filter it to just the bits we need, adjusting the count variable to 1.
2. Separate out the restricted options text block from that JSON, and modify it by appending the extra line of text.
3. Replace the original restricted options text with the modified restricted options text in a copy of the JSON file.
4. Update the configuration instance with the modified JSON file.

I have not added a test to this script to see whether the line to be added is already in the compute server restricted options, and only add it if it is not already present. That would make the script more complicated. If you want an example of how to do something like that, see my post Add statements to an existing SAS Viya compute context autoexec.

What SAS system options are there, and which can be restricted?

There are hundreds of SAS system options for the programming run-time (over 470 in a SAS Studio compute session in a SAS Viya deployment I have to hand just now), which you can list in your environment by running simply:

proc options;
run;

The Using SAS System Options > Restricted Options topic in the SAS Viya Platform Programming documentation lists 59 options (at the time of writing) which cannot be restricted by a site administrator.

There is a Definition of System Options in the SAS Viya Platform Programming Documentation. There's an identical definition in the SAS® 9.4 and SAS® Viya® 3.5 Programming Documentation: this is not a rapidly changing part of our software, but it remains something programmers and administrators should still be familiar with.

Options are organized in option groups, which can be listed with:

proc options listgroups;
run;

With so many options listed, filtering the options to those in a specific option group can help you find ones relevant to an aspect of the SAS programming run-time that you are trying to modify, e.g.:

proc options group=CAS;
run;
proc options group=EMAIL;
run;
proc options group=MACRO;
run;
proc options group=PERFORMANCE;
run;
proc options group=SASFILES;
run;
proc options group=SECURITY;
run;
proc options group=SORT;
run;

If you run the statements above in your environment, you may spot some options which you may want to set to specific values, and not want your users to be able to change. These might include any of the SAS options in the CAS, EMAIL, PERFORMANCE group, and selected options in other groups such as SASAUTOS from the MACRO group or ENGINE in the SASFILES group.

If you are a SAS programmer, you probably know about SAS system options like OBS, FULLSTIMER, MPRINT, MLOGIC and likely many more. They are used to specify aspects of the way the SAS programming run-time executes your program, and what you see in the program logs. You might modify the settings of some SAS options between programs, or from time to time, or even part-way through some of your programs, to adjust aspects of the way your programs run or what you see in the logs to suit your needs.

But you might be persuaded that there are some SAS options which end users really ought not to be allowed to change, in a production environment. Any options you think are best left under the administrator's control are good candidates for the restricted_options sections.

Given that SAS options are such an old and fundamental feature of the SAS programming language, there are lots of resources which mention ways you and your users can modify them to your advantage in your SAS Viya deployment. And now you know that as a SAS administrator, you can retain control of options you would prefer that your end users do NOT modify.

See you next time!

Find more articles from SAS Global Enablement and Learning here.

1 Like