sas-viya batch jobs, file sets and the SAS administrator

4 Likes

There are several posts on running SAS programs in batch using the sas-viya command with the batch plugin. In this post we will look at some topics that have not been discussed before.

In case you are not familiar with the sas-viya batch plugin, I do suggest to have a look at How to Run SAS Programs in Batch in the New SAS Viya and How to Run SAS Programs with Parameters in Batch in SAS Viya to get you started.

Topics being discussed are:

Running a SAS program in batch (without waiting for results)
Listing the running/completed batch jobs
Understanding file sets and how they are used
Getting the results of a batch job
Things the SAS Administrator needs to know

Running a SAS program in batch (without waiting for results)

If you want to run a SAS program as a batch job you can use the sas-viya batch jobs submit-pgm command. The two options, --context and --pgm-path are required. A context contains the information needed to run a SAS batch server. By default, one batch context is defined, with the name of "default". The SAS program simple.sas used in the example below, is located on the same machine from which you are running the sas-viya command. In the command below a relative file name is used, so the file is searched in the current directory.

sas-viya batch jobs submit-pgm --context default --pgm-path simple.sas

>>> The file set "JOB_20230621_144333_122_1" was created.

>>> Uploading "simple.sas".

>>> The job "b1b3b6b4-8fdf-4cf0-af20-88021ae5f9d0" was submitted.

As you can see from the command output

A file set is created, more details on the file set later
The program provided is uploaded to the file set
An unique id for the job is returned

Jobs are run in a pod on the Kubernetes cluster. Pods created using the sas-viya batch jobs submit-pgm command are named using this convention: "sas-batch-server-<unique-id>". Each job also has a name. By default it is the name of the SAS program. In our example, "simple" is used as the job name. You can use the --name option to provide a different name for your job. The SAS program runs in the back, we will collect the results of the job later. There are additional options that allow waiting for the results, see an example here How to Run SAS Programs in Batch in the New SAS Viya.

You can add additional files to the file set using the --job-file option. This could be another SAS program, or any other file. If you need more than one file, repeat the --job-file option with the additional file. These files are made available in the file set created when you submit the job. While the SAS program executes, the file set is stored on the file system of the pod. We will look at a file set and how you can access the contents in the topic on file sets.

List the running/completed Jobs

To list the running/completed jobs use the following command:

sas-viya batch jobs list --sort-by submittedTimeStamp

Please note the --sort-by option. It ensures that we see the list of jobs as they have been submitted (refer to the built-in command help for other fields to sort on). If you run this command as an administrator, all the jobs from all the users are displayed. For a non-administrator, only their own jobs are displayed.

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

The time information is returned as UTC. If you need more details, for instance the file set id associated with the job, use the --details option. To get the listing back as JSON add the --output fulljson option right after the sas-viya command.

To limit the list of jobs based on some criteria, use the --filter option. Here are a few examples:

list all the jobs with "fancy" in their name (this filter is case sensitive) sas-viya batch jobs list --sort-by submittedTimeStamp --filter 'contains(name, "fancy")'
list all the jobs with "fancy" in their name (ignore the case) sas-viya batch jobs list --sort-by submittedTimeStamp --filter 'contains($primary, name, "fancy")'
list all the jobs with a start time after a given value (valid values are "yyyy-mm-dd", "yyyy-mm-ddThh:mmZ", "yyyy-mm-ddThh:mm:ssZ") sas-viya batch jobs list --sort-by submittedTimeStamp --filter 'gt(startedTimeStamp, "2023-06-22T09:00Z")'
list all the jobs that have a state of failed sas-viya batch jobs list --sort-by submittedTimeStamp --filter 'eq(state, "failed")'

See the built-in help of the --sort-by option for a list of fields you can filter on. For more details on the supported functions, check Filtering with the filter query parameter

File Sets

Each time you submit a SAS program a file set is created which contains the program to run, the SAS log of your program, files you added using the --job-file option and any files that have been written to this location by the SAS program.

The contents of the file set is accessible from the SAS program using the BATCHJOBDIR environment variable. You can read and write from/to this location. The sample below shows how to get the directory name and the file set name.

%let batchjobdir = %sysget(BATCHJOBDIR);

%let fileSet = %scan(&batchjobdir, -1, /);

If your program creates printed output, for example proc print, then a <program-name>.lst file is written to the file set location. If you want to create html, PDF or any other supported ODS output format you would add code like this:

ods _all_ close;

ods pdf file="&batchjobdir/myresult.pdf";

proc print data=sashelp.class;

run;

ods pdf close;

Once the SAS program ends, any file in the file set, this includes the SAS log (<program-name>.log), will be copied to this SAS Content folder: /User/<userid>/Application Data/sas-batch/fileSets/<file set-name>. This ensures, that the contents of the file set is available after the pod running the SAS program has ended.

Get the result of a batch job

In order to get the results of a batch job, the contents of the file set, use this command:

sas-viya batch jobs get-results --job-id <unique job-id>

The output of the command looks like this:

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

If no --job-id is provided then all the results will be downloaded to the current directory. You can use the --results-dir option to specify another directory. In addition to the files from the file set, a file job.info is written that has this content:

Job ID: 2f2726b6-9b82-4a67-878d-588c101f87e4

Job name: simple

File set ID: JOB_20230622_120326_837_1

Time job submitted: 2023-06-22 12:03:27 +0000 UTC

Time job started: 2023-06-22 12:03:31 +0000 UTC

Time job ended: 2023-06-22 12:03:34 +0000 UTC

Name of execution host: 10.42.0.166 Return code: 0

The sas-viya batch jobs get-results command supports the same --filter option like we saw above with sas-viya batch jobs list command.

Once the get-results command has finished, the corresponding folder in SAS Content gets deleted and the job is no longer listed. Remember, as an administrator you can get the results from all users.

If you run a lot of jobs for testing purposes, you may want to "delete" all the jobs. Use this command to get the results of all jobs and write it to a temporary directory (use a filter as shown above for a subset).

tmpDir=results_$(date +%s)

mkdir $tmpDir

sas-viya batch jobs get-results --results-dir $tmpdir

It is now up to you to decide what you want to do with the contents.

A job can also be deleted using sas-viya batch jobs delete --id <job-id>. This command only deletes the job but not the associated file set. However once the job id is deleted you can no longer use the get-results command to get the contents of the file set. There is the sas-viya batch filesets command that supports these operations list, list-files and delete. A file set that has an associated job can not be deleted.

Good to know for the SAS Administrator

By default authenticated users can run SAS programs in batch
As mentioned before, an administrator can see all batch jobs submitted and can also read the results of all jobs
Batch contexts can be created/edited using either SAS Environment Manager or the sas-viya batch contexts command.
As of SAS Viya 2023.02 a batch program can be run under a shared account, see Configure Batch Servers to Run under a Shared Account
There are general Configuration Instances to control autoexec and configuration settings, see Configuration Instances: Batch Service
On the context level, SAS system options can be set
By default, no CAS server related system options are set. For the SAS program being able to communicate with the CAS server the corresponding system options need to be defined either on the Configuration Instance level or the context level (or in your SAS program).
A batch server is running in lockdown mode by default, see Lock Down the SAS Batch Server for more information
By default the batch server is not configured to run Python code using Proc PYTHON, see Submit Python code to SAS Viya from the command line on how to configure Python support.
Keep in mind that the sas-viya command as well as the plugins get updated frequently. See Get the CLI and Its Plug-Ins for more details.

Conclusion

Wherever you have the sas-viya command available (supported on Windows, Linux and OSX), you can use it to run a SAS program in batch. You can pass files into the pod so these files can be used as input in your SAS program. By default the results returned from a batch program include the program being run, the SAS log and optional printed output (Listing format). The SAS program can write files into the file set to be returned. This maybe ODS output or any other file, for example XLSX or CSV created using using Proc EXPORT.

I would like to thank my colleagues @AjmalFarzam , @DarrellBarton and @ScottMcCauley for their contributions.

References

Find more articles from SAS Global Enablement and Learning here.