Compute

The Compute API enables users to submit and execute SAS code using REST calls. Users can manage Compute contexts, create sessions, submit jobs, and access information about the session.

The Compute API defines the replacement for the application servers that were used for SAS 9. The Compute API enables clients to perform the following tasks:

  • Submit and execute SAS code.
  • Obtain the SAS log or listing information from executed SAS code.
  • View output that is generated by a SAS code submission.
  • Access SAS data sets that are created by a SAS code submission.
  • Access SAS filerefs that are created by a SAS code submission.
  • Access SAS variables that are defined and used in a SAS code submission.
  • Retrieve information about engines that are available in a session.

The Compute API can define a Compute context using Create, Read, Update, and Delete operations. A Compute context is analogous to the SAS Application Server from the SAS V9 engine. There are also endpoints that enable you to request a Compute session. A Compute session runs on a SAS Compute Server and serves as the access point to SAS language processing in this environment. A Compute session replaces the functionality of the SAS Workspace Server and SAS Stored Process Server from SAS 9.

The Compute API enables the following tasks:

  • Define a Compute context.
  • Manage a Compute context.
  • Create a Compute session to work in.
  • Reference resources from other APIs.
  • Submit a job to run in a Compute session. A job can be a single line of SAS code or a complex SAS program.
  • Obtain the log of all submitted SAS code during a Compute session.
  • Obtain the listing output of all submitted SAS code during a Compute session.
  • Obtain links to results for output that is generated by a job that you submitted during a Compute session.
  • Access SAS data sets that are available to you.
  • Access files via SAS filerefs that are available to you.
  • Access SAS macro variables that are defined during a Compute session.
  • Retrieve information about available engines in the system.
  • Access or update SAS options that are available during a Compute session.

The Compute API also acts as a provider for the following APIs. The Compute API registers itself as a provider with the name Compute when it interacts with these APIs.

  • Job Execution API
  • Data Sources API
  • Data Tables API
  • Row Sets API

Life Cycle Management

There are several resources that are available to the Compute API. These resources have different life cycles, depending on their usage by clients. This section describes the life cycles of these resources.

SAS Compute Server

A SAS Compute Server is a running process. The Compute API forwards requests to the SAS Compute Server for processing. When a client requests a Compute session from the Compute API, the Compute API determines whether there are any SAS Compute Servers that can handle the request. The client provides a Compute context when requesting a Compute session, and the Compute API attempts to find a suitable SAS Compute Server to handle the request for that context. If no suitable SAS Compute Server is found, a new SAS Compute Server process is launched, and a Compute session is created for the new SAS Compute Server.

Compute Session

A Compute session is created on the SAS Compute Server when a client needs to perform tasks. The client makes a request for a session via the Compute API. The Compute session is the starting point for most actions that take place inside of the SAS Compute Server. Currently, a Compute session lifetime is controlled by the client. When a client has completed work with a Compute session, it then uses the appropriate Delete command to destroy the Compute session.

You can configure Compute sessions to time-out after a time of inactivity. You can set the time-out period in the Compute context or in the Compute session request that you use to create the Compute session. After the specified period of inactivity passes, the session is destroyed.

Note: Compute sessions are strongly tied to the SAS Compute Server that they are running on. A Compute session cannot be migrated to another SAS Compute Server, and the Compute session state is not maintained if the associated SAS Compute Server fails.

Jobs

Jobs are units of SAS code that are executed by the client in the Compute session. A job has a state that describes where it is in its life cycle. A completed job might continue to be accessed for information such as listings, logs or results. Output from a job might be available to the data and file endpoints of the Compute session.

After a job is destroyed via the appropriate DELETE request, the log, listing, and result resources that are associated with that job are no longer available via the jobs path for a session. However, the log, listing, and result resources are available to the session, and you can reach them via the session/ endpoints.

If a session that contained a job is destroyed, then all jobs and all resources that are associated with those jobs are destroyed as well.

Logs, Listings, and Results

The log, listing, and result resources are generated by the execution of a job. However, their lifetime is governed by the Compute session that the job was executed in. Multiple jobs can execute in a session. Each of these jobs might create its own logs, listings, and results. You can access the resources for a particular job by going directly to the desired endpoint under sessions//jobs/. However, you can also access all logs, listings, and results for the entire session by going to the corresponding endpoint under sessions/.

When a job is destroyed, the content of the log, listing, and result resources that are associated with that job are still available via the session. When a session is destroyed, all logs, listings, and results are destroyed, as are all jobs for that session.

Data Access

The Compute session allows access to any data sets that are available. These data sets might be generated from a variety of sources:

  • an underlying SAS configuration, such as sasv9.cfg (for example, SASHELP)
  • libraries that are configured when a session or job is requested
  • a job that executes in a session

Clients might also use the data endpoints to create libraries and upload data sets that are used by SAS code that is executed in the same Compute session.

Regardless, generated data sets are associated with a Compute session and are available as long as the Compute session is available. When a session is destroyed, the generated data sets are no longer available via that session. If the data sets are part of a persisted data storage area, you can continue to access them. If the generated data sets are stored in a transient area that is owned by the destroyed Compute session (for example, SASWORK), then the data sets are destroyed also.

File Access

A Compute session enables you to access files that are available to it.

Your Compute session can access files via the /filerefs endpoint with SAS filerefs. These filerefs are generally created by the SAS code that executes within a job. Clients might create filerefs via the /filerefs endpoint, and you can use these filerefs in SAS code that executes in the same Compute session.

These filerefs are associated with a Compute session and are available for the duration of the Compute Session. When a session is destroyed, associated filerefs are no longer available via that session. If the underlying files are part of a persisted data storage area, then those files continue to exist. If the files are kept in a transient area owned by a destroyed Compute session, then those files are also destroyed.

Your Compute session can also access files via the /files endpoint with file or directory paths. Files or directories can be created through the /files endpoint. You can also retrieve file or directory properties, upload files, or download files. Via the /files endpoint, you can also do typical file operations like copy or rename a file.

When you provide a file or directory path in the /files URL, follow these guidelines:

  • Replace a forward slash character '/' with "~fs~".
  • Replace a backward slash character '\' with "~rs~".
  • Replace a semicolon character ';' with "~sc~".
  • Replace a tilde character '~' with double tildes "~~".

Attributes

The following attributes can be set in the media types for requests that are used in the Compute API.

sessionInactiveTimeout

Sets the inactivity time-out for a session. If specified in a Compute context request, then the attribute is in effect for any session that is created from that context. If specified in a session request, then the attribute applies to that session only.

  • If the value is positive, then a session is terminated if it is inactive for longer than the specified time period.
  • If the value is negative or unset, then the default value of 15 minutes is used.
  • If the value is 0, then the session does not terminate due to inactivity.
resetLogLineNumbers
  • Valid: Job Request
  • Type: Boolean
  • Availability: Added in version 2 of the resource.

If this attribute is set for a job request, then the log line numbers are reset to 0 immediately before the job begins execution.

allowXCMD
  • Valid: Context Request
  • Type: String
  • Availability: Added in version 3 of the API.

This attribute instructs the Compute sessions that are created from the Compute context to allow XCMDs. By default, XCMDs are disabled. An administrator can choose to enable XCMDs. By setting the value to "true", the administrator can allow any authorized user of the Compute context to use XCMDs. If the administrator sets the value to a name, such as "powerUsers", then the users that are members of that Identity group are allowed to use XCMDs.

homeDirectory

This attribute specifies the home directory for a Compute session. All relative paths in /files endpoints are relative to the home directory of a Compute session. By default, the home directory of a Compute session is set as the current working directory of the Compute server. The home directory of a Compute session remains as a constant for the duration of that Compute session. The home directory has the same life time as the Compute session.

unsafeJobCharacters
  • Valid: Context Request
  • Type: String
  • Availability: Added in version 3 of the API.

This attribute specifies the characters that the Compute session should remove from a value when the characters are part of a variable value that is received as input to a job. By default, the following character is stripped out:

  • ; (semicolon)

The following characters are masked by the %NRSTR quoting function:

  • & (ampersand)
  • " (double-quote)
  • ' (single-quote)
  • % (percent)

When this attribute is set, it lists the characters that should be removed in addition to the characters that are listed above. The characters that are listed above are always handled in the manner indicated when this attribute is enabled. If you set this attribute to an empty string (""), then the feature is disabled. Even when the attribute is disabled, semicolons (;) are always stripped from a variable value.

runServerAs
  • Valid: Context Request
  • Type: String
  • Availability: Added in version 3 of the API.

This attribute specifies the account that runs any servers that are launched for this Compute context. The specified account is considered a shared service account, and all Compute servers that are launched for this Compute context run under this account. The value should correspond to the user name of a Service Account Credential that is stored by the Credentials service. See "Service Account Credentials" in the Examples section for more information.

reuseServerProcesses
  • Valid: Context Request
  • Type: Boolean
  • Availability: Added in version 3 of the API.

This attribute enables servers that are launched for this Compute context to be reused. The servers must also have a runServerAs attribute specified.

serverInactiveTimeout
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 3 of the API.

This attribute is applicable when reuseServerProcesses is enabled. The attribute value specifies the amount of time in seconds that a server is allowed to remain inactive before being terminated. A server is inactive when it has no currently active Compute sessions.

serverReuseLimit
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 3 of the API.

This attribute is applicable when reuseServerProcesses is enabled. The attribute value specifies the maximum number of times that Compute sessions can be created on each server that is launched. If this value is n, then when the nth Compute session is created, no additional sessions are created. When the nth session ends, the server terminates.

serverMinAvailable
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 5 of the API.

This attribute is applicable when reuseServerProcesses is enabled. The attribute value specifies the minimum number of Compute server processes that the Compute service keeps available. This setting allows for an application to have a server process ready to use and not have to wait for the process to launch.

NOTE: Limitations that might be imposed by the environment such as resource constraints or workload management rules are followed.

statusNotification
  • Valid: Job Request
  • Type: Boolean
  • Availability: Added in version 15 of the API.

If this attribute is set for a job request, then the log will contain progress information and SYSECHO lines encountered during job execution.

queueName
  • Valid: Session Request
  • Type: String
  • Availability: Added in version 16 of the API.

This attribute specifies the SAS Workload Orchestrator queue that the Compute server should be scheduled to run in. If the Compute context being used also specifies a queue, the context's value overrides this value. If a server does not need to be started to fulfill the session request, this attribute is ignored.

jobNamePrefix
  • Valid: Session Request
  • Type: String
  • Availability: Added in version 16 of the API.

This attribute specifies the desired prefix for the Compute server's pod name. The jobNamePrefix must meet the following rules:

  • Contain only lowercase letters, numbers, and hyphens.
  • Start with either a lowercase letter or number.
  • End with a hyphen.
  • Contain no more than 100 characters

If these rules are not met, the jobNamePrefix is modified to meet these rules. If a server does not require a restart to fulfill the session request, this attribute is ignored.

serverLaunchTimeout

When a new server is started to fulfill a request, this attribute specifies how long the service waits for the new server to reach a running state. The value must be greater than zero seconds.

taskTimeout
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 21 of the API.

The timeout specifies the maximum duration a task can run before being terminated. It applies to all tasks executed for the context and is limited by the deployment's maximum task timeout setting, sas.compute.service.tasks.maxTimeout, which can be configured using SAS Environment Manager. The taskTimeout value must be greater than 0 seconds and less than or equal to the deployment's maximum time-out value.

serverMaxAvailable
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 22 of the API.

This attribute is applicable when reuseServerProcesses is enabled. It sets an upper limit on the total number of reusable Compute servers that can be active (including in-use, idle, and pending) for the context. If this limit is reached, the Compute service will not start additional servers, even if the pool is under pressure. This cap ensures environments can control resource consumption for a given context.

serverPoolScaleThreshold
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 22 of the API.

This attribute is applicable when reuseServerProcesses is enabled. It defines the threshold (as a %) of total servers that must be in-use before the Compute service considers scaling up the pool. For example, a value of 75 means that if 75% or more of the servers are in use, the service will attempt to proactively start additional servers to handle expected future load.

serverPoolScaleStep
  • Valid: Context Request
  • Type: Integer
  • Availability: Added in version 22 of the API.

This attribute is applicable when reuseServerProcesses is enabled. It determines the number of new reusable servers the Compute service should attempt to start when the serverPoolScaleThreshold is exceeded. If the attribute is not set, the default scale step is 1.