SAS Job Execution Web Application 2.1 - User S Guide
SAS Job Execution Web Application 2.1 - User S Guide
Overview
A SAS Viya job consists of a program and its definition, which includes information such as the job name, author,
and creation date and time. You can use jobs for web reporting, performing analytics, building web applications,
and delivering content to clients. One such client is the SAS Job Execution Web Application. This client works
with jobs that contain SAS code. These jobs can access any SAS data source or external file and create new
tables, files, or other data targets that are supported by SAS.
By default, jobs that are submitted through the SAS Job Execution Web Application begin with the %JESBEGIN
macro and end with the %JESEND macro. These macros produce HTML output by default.
An HTML input form can be created to provide a user interface to the job. The job definitions and HTML input
forms are assigned unique identifiers, stored in the SAS Infrastructure Data Server, and executed in real time by
client applications.
The SAS Job Execution Web Application is a web-based client used to create, manage, and execute jobs. This
application, written in Java, provides access to data in combination with a powerful array of analysis and
presentation procedures running on a server. No SAS software is required on the client machine.
To access and analyze data, a web user typically completes an HTML input form displayed by the SAS Job
Execution Web Application. When the user selects the option to submit the information, data specified in the
form is passed to a waiting SAS session as global macro variables. The SAS program runs and the results are
returned to the web browser.
You do not need Java or script programming experience to use the SAS Job Execution Web Application. You
can create the web user interface and retrieve SAS data for display on the web using only HTML and SAS code.
Use the SAS Job Execution Web Application if you
n want to analyze and display information dynamically on the web and let your web users immediately retrieve
the information that they need.
n have SAS programming experience but little or no web programming experience. You can create the web
user interface and retrieve the SAS data for display on the web.
n want to create applications that provide web output without investing a lot of programming time.
The SAS Job Execution Web Application has several types of users, as follows:
2
n End users enter information in an HTML input form, select a link, or view an inline image that is displayed in
a web browser.
n Web page authors create the HTML input forms or pages that collect and submit input to the SAS job. These
individuals could be SAS application developers.
n SAS job program component developers create the SAS programs that receive information entered in the
HTML input form.
The SAS Job Execution Web Application executes a stored job when it receives a request with a parameter
indicating the location of the job. The request is initiated by accessing a URL with the following general format:
http://host:port/SASJobExecution/?_program=/SomeFolder/Hello World
In this example, the Hello World job stored in the /SomeFolder location is executed.
Various SAS Viya services are used to retrieve the job, submit it for processing, and display the job output. The
following figure shows the components that are used to run a job:
Browser
Embedded web
application server Job Execution Compute Launcher
SAS Job Execution service service service
Web Application
SAS
Launcher
Server
Job
Folders Files
Definitions
service service
service SAS
Compute
Server
1 A request is submitted to the SAS Job Execution Web Application, usually initiated by a web browser client.
2 If the job is referenced using a folder path, then the job location is obtained from the Folders service. This
step is skipped if the job location was specified in the _JOB parameter.
3 The job definition is retrieved from the Job Definitions service by using the job location obtained in step 2.
4 Input parameters, execution parameters, and the job definition are submitted to the Job Execution service.
5 The request is passed to the Compute service, which uses the Launcher service to start a Compute Server.
Note: Each client user must have a user account on the Compute Server machine to run a request.
6 The SAS program runs in the Compute Server and creates output in the SAS Infrastructure Data Server
using the Files service. The files are associated with the job execution object to facilitate retrieval.
3
Note: The Compute Server can access the SAS Cloud Analytic Services (CAS) server though the CAS
procedure or through the CAS LIBNAME engine. For more information, see SAS Cloud Analytic Services:
CASL Reference and SAS Cloud Analytic Services: User’s Guide, respectively.
7 The Job Execution service monitors the job execution and alerts the SAS Job Execution Web Application
when the job has completed.
8 The SAS Job Execution Web Application instructs the web browser to use the Files service to retrieve the
desired output files linked to the job execution object. If the _SAVEFOLDER option is used, then the output is
saved to the specified folder.
9 The job execution object has an expiration time, which is set when the job has finished executing. When it
expires, the job execution object and all files associated with it are deleted.
If you do not specify a value for port, the default value of 80 is used.
Accessing Content
The SAS Content page enables you to locate, manage, and execute job-related files. If the output of a job is
saved to SAS content folders, it can also be displayed from this page. The SAS Content page appears by
default when you enter the SAS Job Execution Web Application, but if you are on another page, you can click
to access it. The left pane displays folders and their contents, and the right pane is used as a presentation and
working area for the various job functions:
See the Creating a Simple Job that Uses DATA Step Code and Passing User Input to Your Job Using an HTML
Input Form sections in “Development Concepts” on page 19 for more information about creating and editing
files.
4
The full version of the SAS Content page is available to users who have authorization to develop jobs. It can be
accessed using the /developer path. A more limited SAS Content page is available to users who are allowed
only to execute existing jobs and view output. It can be accessed using the /user path. The display and
capabilities are automatically adjusted according to the authorization of each user. For example, HTML input
forms are displayed only for developers. By default, all users have authorization to develop jobs. See “Changing
Access to Application Functions” on page 17 for more information about how to assign users access to
developer or user views.
Click to view general properties of a job or to add parameters to the job. See “Passing User Input to a Job
Using a Job Definition Parameter” on page 23 for more information about setting parameters.
Click to retrieve the output from the most recent execution of the job, if it is still available. The output is
displayed in the right pane.
Select a job and then click to submit a job for execution. The following dialog box with execution options
appears when you click :
5
You can add parameters using the format name1=value1&name2=value2. Select the New window option to
display the job output in a new browser window. The Show log option adds the _debug=log parameter setting
to the request. These options remain in effect for job submissions during the current browser session.
The following two URL parameters can be used to alter the folder list for the SAS Content page:
Parameter Description
_path=/SomeFolder Makes the root of the display the indicated folder path and
displays items only in this folder and its subfolders
See “Accessing Application Pages through a URL” on page 6 for more information about accessing pages
through a URL.
Managing Jobs
Click to access the Jobs page, where you can display and maintain jobs that have run previously and have
not yet expired.
Click to save all output from the job. In the Save As dialog box, specify the folder location and file name for
the output. If multiple output files were created, then you are prompted for a location and file name for each file.
SAS Environment Manager is used to schedule jobs. Click to open the Jobs page, where you can access the
Scheduling tab. See SAS Viya Administration: Jobs for more information about scheduling. See “Scheduling a
Job” on page 12 for more information about using the _ACTION parameter to schedule a job.
Each row of the table lists a previously submitted job, with information about the location of the job, its status,
run time, who submitted the job and when, and when the job expires.
You can specify the _PROGRAM input parameter to display results for a single job. For example, the following
URL displays results only for the Hello World job:
http://host:port/SASJobExecution/jobs?_program=/SomeFolder/Hello World
The value of the _PROGRAM parameter is case-sensitive and must exactly match the location and name of the
job.
6
Click to access the Samples administration page, where you can view a table of available samples. This is a
list of items available for installation, not those that have already been installed.
To install samples and use them, copy the sample job definitions and HTML input forms supplied by SAS to a
folder. Select the desired items and then click Copy to. In the folder selector dialog box, select a destination
folder and then click OK to copy the items. If an item already exists in that location, an option to skip, replace the
item, or quit copying is presented.
Copying sample job definitions and HTML input forms to a folder is typically a one-time operation performed as a
post-installation step.
For example, use the following URL to display and execute job files:
http://host:port/SASJobExecution/user
Executing Jobs
When the SAS Job Execution Web Application receives this parameter, the job location is obtained from the
program path and the job definition is retrieved from the Job Definitions service.
Alternatively, an exact location can be entered using the _JOB parameter. The Job Definitions URI, which
contains the unique identifier for the job, is specified in the following form:
_job=/jobDefinitions/definitions/3b9f3a5e-deb1-4873-a90a-be6280e35deb
_program /Folder1/myJob
p 123
Here is an example of specifying the HTML input form using an input parameter:
http://host:port/SASJobExecution/form/?_program=/Folder1/myJob&_form=/Folder2/myJobForm
The HTML input form named myJobForm stored in /Folder2 is displayed. Note that the HTML input form does
not need to be in the same folder as the job (/Folder1) nor does it need to have the same name as the job
(myJob).
If the _FORM parameter is not specified, then an HTML input form with the same name and location as the
corresponding job is displayed, if it exists:
http://host:port/SASJobExecution/form/?_program=/Folder1/myJob
The HTML input form named myJob stored in /Folder1 is displayed. The sample jobs provided by SAS take
advantage of this feature.
Alternatively, you can use the _ACTION input parameter in the URL instead of the /form path. The previous
examples become:
http://host:port/SASJobExecution/?_action=form&_program=/Folder1/myJob&_form=/Folder2/myJobForm
and
http://host:port/SASJobExecution/?_action=form&_program=/Folder1/myJob
Use the Properties function of the SAS Content page to specify _FORM as a preset job parameter. This
technique is useful when you have multiple jobs that need to use the same HTML input form.
Note: You must have access to developer functionality to modify properties for a job.
Suppose that you have two jobs that use the HTML input form name Shared Input Form stored in the /Folder2
folder. Specify /Folder2/Shared Input Form for the _FORM parameter of each job. The input form is then
displayed when both jobs are run using /form or _action=form, without the need for specifying _FORM in
the URL:
http://host:port/SASJobExecution/form/?_program=/Folder1/myJob1
and
http://host:port/SASJobExecution/?_action=form&_program=/Folder1/myJob2
See “Passing User Input to a Job Using an HTML Input Form” on page 24 for an example of how to use an
HTML input form to pass input to a job.
* All files
9
state??.csv CSV files beginning with state and ending with any two
characters (for example, state01.csv)
retail.htm,retail.pdf,class.htm,class.p Only the files that are listed in the order in which they are
df listed
Use _action=json if you have an application that requires a list of result files in JSON format. Here is an
example:
http://host:port/SASJobExecution/?_program=/Folder1/myJob&_action=json
Use the URI in the HREF property to retrieve the _webout.htm file.
The following example uses the _RESULTFILE and _OMITTEXTLOG parameters to return all files, including the
SAS log:
http://host:port/SASJobExecution/?_program=/Folder1/myJob&_action=json
&_resultfile=*&_omittextlog=false
Always begin with %opt- (case insensitive) followed by a name not used by another input parameter. These
parameters can be specified in an HTML input form, as job definition parameters, or in the query string. No SAS
macro variables are created for this type of input parameter.
The following table shows sample values for setting a single option using an HTML input form or job definition
parameter:
%opt-myopt linesize=max
The following table shows sample values for setting more than one option using an HTML input form or job
definition parameter:
%opt-myopt1 linesize=max
%opt-myopt2 nobyline
When specifying the parameter as part of the query string, be sure to URL encode the percent sign ("%") in
%OPT- and also the equal sign ("=") if it is present in your option value. For example, use this URL parameter to
specify 200 for the LINESIZE option:
http://host:port/SASJobExecution/?_program=/Folder1/myJob&%25opt-myopt=linesize%3d200
_timeout=60
The default value can be set using the EXECUTETIMEOUT configuration parameter.
Specifying zero (0) indicates no expiration, and the output files is not deleted. The default value can be set using
the EXPIRATION configuration parameter.
Background Processing
Use the _ACTION job parameter to perform several operations. Specify the following value to execute a job in
the background without waiting for completion:
_action=background
You can use the Jobs page or in the SAS Content page to view the results once the job has finished running.
For all jobs that are submitted, the job ID is returned in the HTTP header X-SAS-JOBEXEC-ID. For jobs that run
in the background, the job ID can be used as follows to poll the jobExecution service to identify the state of the
job:
/jobExecution/jobs/5d21f17b-5f85-4a49-9c34-319174eb741f/state
When the job has finished running, you can use the job ID as follows to view the results:
/SASJobExecution/?_jobexec=/jobExecution/jobs/5d21f17b-5f85-4a49-9c34-319174eb741f
Jobs run in the background expire after 24 hours, unless a different duration is specified using the
_EXPIRATION parameter. Use the Jobs page to set the expiration after a job has executed.
Perform the following steps to use the BACKGROUND configuration parameter to specify a custom HTML page
to display instead of the default message:
1 Create an HTML file with your customized message and then save it to a folder. See “Passing User Input to a
Job Using an HTML Input Form” on page 24 for more information about creating an HTML file.
2 Follow the instructions in “Setting Configuration Properties” on page 14 to create the BACKGROUND
property with the full path and name of the HTML file. For example, specify /Folder/My Custom
Background Message as the value.
Wait Screen
You can use the _ACTION job parameter to display a wait screen with informational text while the job is
executing:
_action=wait
The default value for the text is Please wait. Use the WAITTEXT configuration parameter to specify the text
of the wait message.
Note: The wait value works only when _ACTION is being used as a URL parameter.
12
This avoids the time needed to execute the job in the Compute Server and can be used to provide semi-static
reports. This feature can improve performance and reduce server load if multiple users request a job that
produces exactly the same results.
If there is no previous output, then you receive an error message indicating that previous job output does not
exist.
The _ACTION job parameter also accepts a comma-separated list of values. Add execute to force the job to
execute if the previous job output does not exist:
_action=lastjob,execute
Scheduling a Job
When you execute a job, you can use the _ACTION parameter as follows to save the job definition and
parameter values in the Scheduling table in SAS Environment Manager:
_action=schedule
Use SAS Environment Manager to complete the steps needed to schedule the job. See SAS Viya
Administration: Jobs for more information about scheduling.
See “Managing Jobs” on page 5 for more information about manually performing this action.
By default, the file names that are specified in the NAME option of the Files service access method FILENAME
statement are used. Existing files are replaced. See the sections about assigning a FILEREF in “Development
Concepts” on page 19 for more information about how to use the FILENAME statement.
The _SAVEFILE parameter specifies the file to save:
_savefile=_webout.html
Only the _webout.html file, specified in the NAME option of the Files service access method FILENAME
statement, is saved. Omit this parameter to save all job output files or if the job creates only one file. Note that
by default, only files named with the pattern _webout.* are returned. Use the _RESULTFILE parameter to
specify return files with names that do not match this pattern.
Specify the parameter multiple times to save only some of the output files created by a job. Only the
_webout.html and _webout.pdf files are saved from a job that creates multiple files:
_savefile=_webout.html&_savefile=_webout.pdf
and
_resultfile=*&_savefile=MyOutput.html&_savefile=MyOutput.pdf
The _SAVEFILE parameter can be used to save a file with a new name:
_savefile=original-name,new-name
_savefile=_webout.html,MyOutput.html
See “Managing Jobs” on page 5 for more information about manually saving job output.
After the job output is saved, it is available in SAS Drive. From there, it can be downloaded, displayed, and
accessed by other applications.
Debugging
Debugging information can be returned to assist in program development and execution. Like the _ACTION job
parameter, _DEBUG accepts a single value or a comma-separated list of values:
_debug=fields,log,time,trace
Use trace to display detailed information about the job execution, including preset and input parameters, the
job definition and SAS code, and results created by the job.
By default, the _DEBUG parameter can be used by any authenticated user. To restrict its usage on a group or
user basis, change the authorization rules for the /SASJobExecution/debug/ key using SAS Environment
Manager. See “Security for SAS Viya Jobs” on page 17 for more information.
Use the DEBUGDISALLOW configuration property to disallow the use of specific debug values for all users.
You can use SAS Environment Manager to view log messages generated by the SAS Job Execution Web
Application. Click to display the Logs Filter and Messages panels. Select jobexecapp in the Logs Filter
and then click Apply to display only the pertinent messages.
Perform the following steps to change the amount of information that is generated in the log:
1 Click in SAS Environment Manager, and then select Definitions from the View drop-down list.
2 Click logging.level to display the properties that are used to configure logging levels.
3 Specify com.sas.jobexec in the Filter field at the top of the right panel.
4 If no properties are found, then you must add one. Click New Configuration and then supply the required
value in the New logging.level Configuration dialog box. Otherwise, select the desired value from the level
drop-down list. For example, specify the following values to set the level to report debug messages:
n For Services, specify SAS Job Execution.
Administrative Tasks
Administration of the SAS Job Execution Web Application consists of setting configuration properties and preset
job parameters, enabling logon options, and installing sample programs. An account belonging to the
SASAdministrators group is required to perform these actions.
Start SAS Environment Manager and then select in the left pane. Select All services from the drop-down
menu in the left pane and then select SAS Job Execution.
The configuration properties are displayed in the right pane and can be changed by selecting in the upper
right corner of the sas.jobexecapp section. To add a new property, scroll to the bottom of the list, click Add
property, and then specify the property name and value in the Add Property dialog box.
The following properties can be changed or added:
contextname SAS Job Execution compute context Compute service context name
15
Use a dollar sign character ($) followed by the property name to perform run-time substitution. Any unresolved
values result in the corresponding parameter being set to a zero-length string. The following table provides some
examples:
The last example illustrates how to assign the value of an HTTP request header to a macro variable using the
general syntax $jobexec.header.name. Be sure to specify header when referencing an HTTP header.
It is good practice to use an underscore character (_) at the beginning of system macro variable names. Refrain
from creating macro variables in your SAS program that begin with an underscore character to avoid overwriting
system macro variable values.
Using an administrative account, click in the left navigation bar to access the SAS Environment Manager
Rules page. If you want to restrict who can create job definitions and job forms, change the rule on /
SASJobExecution/developer/** to specify the specific users or groups that should have developer
capabilities. Specify /SASJobExecution/developer/** in the Object URI field of the Rules Filter and then
click Apply to filter the rules of this URI:
For more information about general authorization and working with authorization rules or about permissions that
you can grant or prohibit, see SAS Viya Administration: General Authorization. For most functions, the SAS Job
Execution Web Application checks permissions based on the HTTP request method used to access the URI.
Use the Read permission to control access to the _DEBUG job parameter. For all other URIs, use the Read
permission to control access to the URI using the HTTP GET method and CREATE for the POST method.
The following table lists the URIs and default principals for all of the application functions:
19
An HTML page is returned when this job runs to completion with the message:
Job completed successfully
Development Concepts
For example, specify _OUTPUT_TYPE=ods_html5 if your job uses ODS to create HTML output. The macro
assigns a FILEREF named _WEBOUT to return output to the web browser or client application and issues an
ODS HTML5 statement.
Note: The %JESBEGIN macro creates HTML5 output by default.
The %JESEND autocall macro cleans up the job execution environment and executes after the SAS code.
If you specify _OUTPUT_TYPE=none, the %JESBEGIN macro displays a list of global macro variables in the
SAS log. Specify _ADDJESBEGINENDMACROS=false to prevent the macros from being added to your code
stream.
See “Samples” on page 42 and “%JESBEGIN and %JESEND AutoCall Macros” on page 84 for more
information about using these macros.
1 Navigate to a folder location where you want to store the job, and then click .
2 Specify the name for the file (this example uses Simple HTML) and accept the default values for the File
type field. Click OK.
3 Click the Simple HTML job and then click to display the Properties dialog box.
21
4 Expand the Parameters group and then click Add a new parameter. Specify the following properties for the
parameter:
Property Value
Name _OUTPUT_TYPE
Click Save.
This job creates HTML output but not HTML output generated by ODS. See “Creating Simple HTML Output
Using ODS” on page 26 for more information about creating ODS output from a job.
5 Click .
data _null_;
file _webout;
put '<html>';
put '<head><title>Hello World!</title></head>';
22
put '<body>';
put '<h1>Hello World!</h1>';
put '</body>';
put '</html>';
run;
7 Click , and then click Close to save the job and close the editor window.
This code writes HTML to the _WEBOUT FILEREF that is assigned by the %JESBEGIN macro. This FILEREF
is assigned based on the value specified for the _OUTPUT_TYPE job parameter. The SAS Job Execution Web
Application displays the HTML written to this FILEREF. See the sections about assigning a FILEREF in
“Development Concepts” on page 19 for more information about this type of FILENAME statement.
Specify the complete path and name of the job in the _PROGRAM URL parameter. Perform the following steps
to get a copy of the URL without input parameters:
1 Click a job to select it, and then click to display the Properties dialog box.
2 Expand the Advanced group to see the location of the job definition details and the URL for submitting the
job. For the Simple HTML example, you might see values such as the following:
SAS global macro variables are created from all query string parameters to the right of the question mark (?) in
the URL. These macro variables are available for use in your SAS program. In this case, a macro variable
named _PROGRAM is created with a value of /SomeFolder/Simple HTML.
The program creates the following output:
You can also execute a job by accessing a link in a web page. Specify the previous URL in the HREF attribute of
an anchor tag:
<a href="http://host:port/SASJobExecution/?_program=/SomeFolder/
Simple HTML">Click here to execute job</a>
Use the content selector pane to navigate to the job that you want to execute, select it, and then click to
execute the job.
23
A global macro variable named MYNAME with a value of John is created before the SAS code is executed, and
it is available for use in your SAS program. Make the following change to the code from “Creating a Simple Job
That Uses DATA Step Code” on page 20:
* Declare input parameter;
%global MYNAME;
data _null_;
file _webout;
put '<html>';
put '<head><title>Hello World! </title></head>';
put '<body>';
put "<h1>Hello %sysfunc(htmlencode(&MYNAME))!</h1>";
put '</body>';
put '</html>';
run;
It is good practice to declare input parameters at the beginning of the program so that macro variables resolve.
Also, use double quotation marks in the PUT statement to resolve the macro variable.
Executing the job using the previous web address creates the following output:
Perform the following steps to specify a default value for the MYNAME input parameter by adding a job definition
parameter:
1 Use the SAS Content page to navigate to the Simple HTML job, select it, and then click .
Note: You must have access to developer functionality to modify properties for a job.
2 Expand the Parameters group and then click Add a new parameter. Specify the following properties for the
parameter:
Property Value
Name myname
3 Select Required only if you want to ensure that a non-blank value be specified for the parameter at run time.
5 Run the job again using the previous URL. The output is now:
Property Value
Name _ACTION
If an HTML input form exists, then it is displayed. Otherwise, the job executes.
Perform the following steps to create a job form named Simple HTML in the same folder as the job:
2 Specify Simple HTML for the name of the file. Select Job form from the File type drop-down list. Click OK
to create the file.
3 Click the Simple HTML form file that you just created and then click .
4 Enter the following HTML code into the editor window, ensuring that you specify the appropriate folder
location in the _PROGRAM attribute:
<!DOCTYPE html>
<head>
<title>Simple HTML Example</title>
</head>
<body>
<br/>
<br/>
</body>
</html>
Alternatively, you can use a text editor or web development tool to create the HTML, and then copy and
paste it into the editor window.
Always specify /SASJobExecution/ in the ACTION attribute of the FORM tag to indicate that the form
data is submitted to the SAS Job Execution Web Application for processing. You can specify _blank in the
TARGET attribute to force the output to always appear in a new browser window or tab. Omit this attribute if
you do not want this behavior.
The first input tag specifies that a non-visual object named _PROGRAM has a value of /SomeFolder/
Simple HTML. This input tag indicates the location and name of the program to execute. The value that you
specify is case-sensitive.
The second input tag specifies a value of execute for the _ACTION parameter, which overrides the default
value specified in the job parameter and executes the job.
The third input tag prompts the user for the name to use in the greeting. This object is named MYNAME and
its default value is World.
The last input tag displays a button with the label Run code.
Click , and then click Close to save the input form and close the editor window.
5 Click the Simple HTML job to select it, and then click . The following HTML input form appears in the right
pane:
26
6 Specify Jane as the name for the greeting and then click Run code.
The web browser uses data from all form elements except the submit button to automatically construct a URL
similar to the URL in “Passing User Input to a Job Using the Query String” on page 23. The form data is
submitted when the button is clicked, resulting in the following URL:
http://host:port/SASJobExecution/?_program=/SomeFolder/Simple HTML&myname=Jane
The results are displayed in a new browser window or tab, using the updated value of the MYNAME macro
variable:
Property Value
Name _ODSSTYLE
This job uses PROC PRINT to display all of the data in the SASHELP.CLASS table:
* Display the SASHELP.CLASS table;
<br/>
<br/>
<br/>
28
</body>
</html>
The MULTIPLE attribute of the SELECT tag indicates that multiple selections are allowed, and the optional SIZE
attribute specifies the number of rows to display when the HTML page is rendered. The name of the SAS macro
variable, COLS, is specified in the NAME attribute.
The OPTION tags specify the values sent to the SAS program as well as the values displayed when the HTML
page is rendered. This example uses display values that differ from the macro variable values:
Gender sex
If you select only First Name and then submit the form, a global macro variable named COLS is created with a
value of name. If you select First Name, Age (y), and Height (in) and then submit the form, the following macro
variables are created:
Because macro variables cannot hold more than one value, a numeric suffix is added to the parameter name to
distinguish between values. The number of values is set in the param-name0 and param-name_COUNT
variables. The first value is set in the param-name1 variable, and so on, as shown in the previous table. Note
that the original parameter macro variable is always set to the first parameter value.
This format is seldom useful in SAS code. For example, the pseudo-array of user selections must be
transformed before they can be used in a VAR or SELECT statement. You can use the PARAM_LIST macro
available in “PARAM_LIST Macro” on page 90 to convert the user selections into a usable format.
Create a job named Multiple Input Values with the following job parameters:
%param_list(mvar=cols, outvar=column_list)
The COLS selection list in the HTML input form is used to choose one or more columns in the SASHELP.CLASS
table. The PARAM_LIST macro takes the individual selections and converts them to a single list that is used in
the VAR statement.
For example, if the user selects First Name, Age (y), and Height (in), then the macro variable COLUMN_LIST,
created by the PARAM_LIST macro, resolves to the following:
name age height
Detailed sales information is displayed when you click a link. Here is the detailed data for Asia:
Add the following code to produce the summarized report with the drill–down links:
31
%let BASE_URL=&_URL.?_program=
/SomeFolder/Drilldown2&_action=wait%nrstr(®ion=);
ods escapechar='^';
data work.shoes_summary;
set work.shoes_summary;
The BASE_URL macro variable is used to create a portion of the drill–down link. The _URL reserved macro
variable ensures that the URL is valid. The job that displays the detail data, Drilldown2, is referenced here. This
job is created in the next step, and you must specify the full path to that job.
The complete drill–down link text is stored in the REGION_LINK variable. ODS inline formatting is used to create
the link using the URL style attribute. This technique creates links for HTML as well as other ODS output
formats. The general syntax of the inline style is:
^{style [url='URL-of-second-job']link-text}
Here is an example of the value of the REGION_LINK variable created in the code:
^{style [url='/SASJobExecution/?_program=
/SomeFolder/Drilldown2®ion=Asia']Asia}
The value of the sales region of interest is passed to the Drilldown2 job using the REGION input parameter.
32
The STRIP function removes any trailing blanks in the data value, and the URLENCODE function handles
parameter values that need to be encoded:
^{style [url='/SASJobExecution/?_program=
/SomeFolder/Drilldown2®ion=Central%20America%2FCaribbean']
Central America/Caribbean}
The PRINT procedure displays the summarized data with links to execution of the detail data program.
Next, create a job named Drilldown2 that displays the detail data using the following job parameters:
Add the following code to produce the detailed report for a specified region:
* Declare input parameter;
%global REGION;
* Include the value of the REGION input parameter in the report title;
Though not required, it is good practice to declare all input parameters using a %GLOBAL statement.
The value of the REGION input parameter, passed to the program as a URL parameter from the link in the
Drilldown job, is used in the report title and also to subset the data so that only the detailed information is
displayed for the specified region.
Run the Drilldown job and then click a link for a sales region. The detailed data for the region appears.
33
Specify appropriate values for email-recipient and email-recipient-domain. Use the HTML3 destination because
some email clients do not support the HTML created by the HTML4 and HTML5 destinations.
The job does not create visual output displayed by the web browser client. You can use _STATUS_MESSAGE to
display a message in the web browser.
You might have to specify one or more system options to successfully send email. See SAS System Options:
Reference for more information about email communications system options.
Unlike the DISK device type, the FILESRVC device writes files to the SAS Infrastructure Data Server using the
Files service, not the external file system. The FILESRVC access method creates global macro variables of the
form _FILESRVC_fileref, where FILEREF is the fileref used in the FILENAME statement. This macro variable
provides a relative URL that can be used to reference and retrieve the file using the Files service (for example, /
files/files/74d8179e-e922-4b58-a8fe-0863b2aa3bfc). See “Report with Download Links” on page
77 for an example that uses this macro variable.
The SYS_JES_JOB_URI macro variable provides a reference to the job execution object. When used with the
PARENTURI option, this ensures that the file is associated with the job execution object. All files associated with
a job execution object can be displayed by the SAS Job Execution Web Application until the job expires. By
default, job output is deleted 30 minutes after it is created. See “Job Output Expiration” on page 11 for more
information about how to change the expiration time. See “Saving Job Output” on page 12 for more information
about how to save a permanent copy of your job output files.
In most cases, you should use the name _webout.htm because the SAS Job Execution Web Application
searches the job results object for an entry named _webout.* and displays the first result that it finds. This
behavior can be altered using the _RESULTFILE parameter.
Use the following format if your web browser does not support rendering PDF files or if you want the content to
be downloaded as a file. Specify the desired file name in the FILENAME attribute of the CONTENTDISP option:
filename _webout filesrvc parenturi="&SYS_JES_JOB_URI"
name='_webout.pdf'
contentdisp='attachment; filename="MyFile.pdf"';
See “Report with Download Links” on page 77 for an example that uses this format.
Use the following format to download RTF content:
filename _webout filesrvc parenturi="&SYS_JES_JOB_URI"
name='_webout.rtf'
contentdisp='attachment; filename="MyFile.rtf"';
name='_webout.json'
contentdisp='attachment; filename="MyFile.json"';
Use the following format if your program uses the tagsets.ExcelXP ODS destination:
filename _webout filesrvc parenturi="&SYS_JES_JOB_URI"
name='_webout.xml'
contenttype='application/vnd.ms-excel'
contentdisp='attachment; filename="MyFile.xml"';
See “Report with Download Links” on page 77 for an example that uses this format.
Advanced Programming
The SAS program for the JSON1 job uses the JSON LIBNAME engine to read the JSON data from the input
parameter and then to convert it to SAS tables:
* Declare input parameter;
%global MYJSON;
data _null_;
file indata;
length str $32767;
str = resolve(symget('myjson'));
put str;
run;
* Use the JSON engine to provide read-only sequential access to JSON data;
* Use the JSON engine to provide read-only sequential access to JSON data;
The output is shown in “Sending JSON Data to a Job Using an Input Parameter” on page 35.
<head>
<title>JavaScript Job Execution</title>
<script>
function submitForm() {
var formData = new FormData();
// Your small JSON object here
var json = {aaa:"AAA", bbb:222, ccc:false};
37
</head>
<body>
<div id="JobResults"></div>
<script>submitForm();</script>
</body>
</html>
When you make a POST request, you must specify the _CSRF input parameter exactly as shown. This tag
ensures that the request is considered non-malicious by sending a Cross-Site Request Forgery token to the
server.
See “Sending JSON Data to a Job Using an Input Parameter” on page 35 for the results and the SAS code used
to process the data.
<!DOCTYPE html>
<html>
<head>
<title>JavaScript Job Execution</title>
<script>
function submitForm() {
var formData = new FormData();
// Your large JSON object here
var json = {aaa:"AAA", bbb:222, ccc:false};
var blob = new Blob([JSON.stringify(json)], {type : 'application/json'});
// Create the input parameter for the JSON data
formData.append("myjsonfile", blob);
// Create other input parameters
formData.append("_program", "/Folder/json2");
formData.append("_action", "execute");
formData.append("_csrf" , "$CSRF$");
// Create the request object
var request = new XMLHttpRequest();
request.addEventListener("error", function(event) {
alert("Something went wrong.");
});
request.onreadystatechange = function() {
if (this.readyState == 4) {
if (this.status == 200) {
// Display the results in the DIV
document.getElementById("JobResults").innerHTML = this.responseText;
}
else {
document.getElementById("JobResults").innerHTML = "Status: " + this.status;
}
}
};
request.open("post", "/SASJobExecution/");
// Submit the form
request.send(formData);
// Display a temporary message in the DIV
document.getElementById("JobResults").innerHTML = "Please wait ...";
}
</script>
</head>
<body>
<div id="JobResults"></div>
<script>submitForm();</script>
</body>
</html>
39
The JSON data is uploaded as a file, using the technique in “Sending JSON Data to a Job By Uploading a File”
on page 36. See that section for the results and the SAS code used to process the data.
<head>
<title>JavaScript Job Execution</title>
<script>
function submitForm() {
var formData = new FormData();
// Create input parameters
formData.append("_program", "/Folder/Simple JSON");
formData.append("_action", "execute");
formData.append("_csrf" , "$CSRF$");
// Create the request object
var request = new XMLHttpRequest();
request.addEventListener("error", function(event) {
alert("Something went wrong.");
});
request.onreadystatechange = function() {
if (this.readyState == 4) {
if (this.status == 200) {
// Store the returned JSON data in a variable for later use
var JSONString = this.responseText;
// Your code to post process the JSON data here
}
else {
alert("Status: " + this.status); }
}
};
request.open("post", "/SASJobExecution/");
// Submit the form
request.send(formData);
}
submitForm();
</script>
</head>
<body>
</body>
</html>
40
Your application can use the URIs in the HREF keys to retrieve the file content and handle it appropriately.
The following HTML input form executes the Report with Download Links sample and then stores the returned
list of files in the JSONString variable:
<!DOCTYPE html>
<html>
<head>
<title>JavaScript Job Execution</title>
<script>
function submitForm() {
var formData = new FormData();
// Create input parameters
formData.append("_program", "/Folder/Report with Download Links");
formData.append("_action", "json,execute");
formData.append("_resultfile", "*");
formData.append("_csrf" , "$CSRF$");
// Create the request object
var request = new XMLHttpRequest();
request.addEventListener("error", function(event) {
alert("Something went wrong.");
});
request.onreadystatechange = function() {
if (this.readyState == 4) {
if (this.status == 200) {
// Store the returned JSON data in a variable for later use
var JSONString = this.responseText;
// Your code to post process the JSON data here
}
else {
alert("Status: " + this.status); }
}
};
41
request.open("post", "/SASJobExecution/");
// Submit the form
request.send(formData);
}
submitForm();
</script>
</head>
<body>
</body>
</html>
%let BASE_URI=%sysfunc(getoption(servicesbaseurl));
* Use the JSON engine to provide read-only sequential access to JSON data;
The SAS_SERVICES keyword specified in the OAUTH_BEARER option ensures that an access token is
obtained using the identity of the user executing the job.
42
Samples
.pointer {
cursor: pointer;
}
43
</style>
The pointer class displays the web browser's pointer cursor when positioned over certain fields. You can
provide your own CSS code or omit the STYLE element if you do not want to use CSS in your HTML input
forms.
<body role="main">
Hello World
This example creates HTML output using DATA step code and returns it to the web browser. An HTML input
form, which accepts a name for the greeting, provides a basic user interface to the program.
Output
<!DOCTYPE html>
<html lang="en">
<head>
<title>Hello World</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
2 <h1>Hello World</h1>
<p>
This sample uses a DATA Step with simple PUT statements to create the output.
</p>
<hr/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
Always specify /SASJobExecution/ for the value of the ACTION attribute of the FORM tag. This ensures that
the SAS Job Execution Web Application processes the form data when the form is submitted.
As the name implies, HIDDEN elements are not displayed on screen, but they pass data to the application
specified in the ACTION attribute. For the value of _PROGRAM, specify the path and name of the program to
execute. A Please wait message is displayed while the program is running when the value for _ACTION is
set to wait, execute. Specify only execute if you do not want to see this message. The value of
_OUTPUT_TYPE specifies that non-ODS HTML output is created by the job. The %JESBEGIN macro issues a
FILENAME statement that supports HTML output.
When the form is submitted, the following global macro variables are defined just before SAS code execution:
_ODSDEST blank
_OUTPUT_TYPE html
myname World
The _ODSDEST macro variable is derived from the value of _OUTPUT_TYPE. It is blank because ODS is not
being used. The MYNAME macro variable is used in the program code.
Program
* Declare input parameter;
46
%global MYNAME;
data _null_;
file _webout;
put '<!DOCTYPE html>';
put '<html lang="en">';
put '<head><title>Hello World!</title></head>';
put '<body role="main">';
put "<h1>Hello %sysfunc(htmlencode(&MYNAME))!</h1>";
put '</body>';
put '</html>';
run;
Program Description
The %JESBEGIN macro assigns a FILENAME statement to return HTML output to the web browser because
html is specified as the value for the _OUTPUT_TYPE input parameter.
The DATA step code writes simple HTML to the _WEBOUT FILEREF that is assigned by the %JESBEGIN
macro, and that HTML is rendered and displayed by the web browser. The value of the MYNAME macro
variable used in the PUT statement is obtained from the value that was specified in the HTML input form. The
HTMLENCODE function is used here to prevent execution of malicious code in the web browser.
The %JESEND macro executes after the last line of code, but it does not close all open ODS destinations
because this sample does not use ODS.
Output
<!DOCTYPE html>
<html lang="en">
<head>
<title>Simple ODS HTML</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<p>
The PRINT procedure creates a simple HTML page that displays the data in the SASHELP.CLASS table.
</p>
<hr/>
</form>
49
</body>
</html>
1 This HTML is similar to the HTML in the Hello World input form.
2 This HTML is similar to the HTML in the Hello World input form.
3 For the value of _PROGRAM, specify the path and name of the program to execute.
_ACTION is set to execute to ensure that the program executes when you click Run Code. The value of
_OUTPUT_TYPE indicates that ODS HTML5 output is created by the job. The %JESBEGIN macro issues a
FILENAME statement that supports HTML output, and it issues an ODS statement using the HTML5
destination.
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but they are not used by the program:
_ACTION execute
_ODSDEST html5
_ODSSTYLE HTMLBlue
_OUTPUT_TYPE ods_html5
The _ODSDEST macro variable is derived from the value of _OUTPUT_TYPE, and it indicates the ODS
destination that is used.
Program
title 'Student Data';
proc print data=sashelp.class noobs;
var name sex age height weight;
run; quit;
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return HTML output to the web browser because ods_html5 is specified as the value for the _OUTPUT_TYPE
input parameter. An ODS statement for the HTML5 destination is also issued.
The ODS HTML5 destination is used because it is the most up-to-date destination for creating HTML output.
The HTML is written to the _WEBOUT FILEREF assigned by the %JESBEGIN macro, and the HTMLBLUE
style, specified in the _ODSSTYLE input parameter, controls the appearance of the output.
The PRINT procedure displays the SASHELP.CLASS table.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
50
Output
51
<!DOCTYPE html>
<html lang="en">
<head>
<title>ODS Output with Embedded Graphics</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<p>
The SGPLOT procedure creates a bar chart using the SASHELP.CLASS
table, followed by a display of the data using the PRINT procedure.
</p>
53
<p>
The SVG image format is not supported for the RTF output.
</p>
<hr/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
1 The first SELECT tag creates a drop-down list output format values. A macro variable named
_OUTPUT_TYPE is created with the corresponding value in the VALUE attribute of the OPTION tag.
54
2 The second SELECT tag creates a drop-down list that enables you to select the ODS graphic image format.
The first item is initially selected and results in a blank value for the _ODS_DEVICE macro variable.
3 The final SELECT tag creates a drop-down list that enables you to select the ODS style to apply to your
output. The HTMLBlue style is selected by default. The selected value is stored in the _ODSSTYLE global
macro variable.
For the value of _PROGRAM, specify the path and name of the program to execute.
The following table lists the display values for the first drop-down list and the corresponding values for the
_OUTPUT_TYPE global macro variable:
HTML5 ods_html5
The following table lists the display values for the second drop-down list and the values for the _ODS_DEVICE
global macro variable:
SVG svg
PNG png
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but they are not used by the program:
_ACTION execute
The _ODSDEST macro variable is derived from the value of _OUTPUT_TYPE and indicates the ODS
destination that is used.
55
The HTML in this form uses some of the same fields as “Simple ODS HTML” on page 46. See that section for
more information.
Program
title 'Student Data - SGPLOT';
proc sgplot data=sashelp.class; hbar age; run; quit;
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return the type of output that is specified in the _OUTPUT_TYPE input parameter to the web browser.
An ODS statement using the HTML5, PDF, or RTF destination is issued based on the value of
_OUTPUT_TYPE. The HTML5 destination is used because it is the most up-to-date destination for creating
HTML output. ODS writes the output to the _WEBOUT FILEREF assigned by the %JESBEGIN macro, and the
style specified in the _ODSSTYLE input parameter controls the appearance of the output.
An ODS GRAPHICS statement that specifies the graphic image format is issued if a value is specified for the
_ODS_DEVICE input parameter. If no value is specified for _ODS_DEVICE, then the best format is used, based
on the ODS destination.
The SGPLOT procedure creates the graphic image using data from the SASHELP.CLASS table, and the PRINT
procedure displays the data.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
The HTML output and the PDF output are displayed by the web browser, and the RTF output is downloaded so
that it can be saved and opened with an appropriate application, such as Microsoft Word.
Output
The following sample output contains selected values, assuming that default selections were made in the HTML
input form.
56
<!DOCTYPE html>
<html lang="en">
<head>
<title>Display Macro Variables</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
58
<p>
The program invoked by this HTML page is used to display the macro variables created for a job.
The SAS Job Execution Web Application creates multiple macro variables when the same name is used
for multiple fields in the HTML input form.
</p>
<hr/>
<p>
The following three text fields are all named TEXT.
</p>
<p id="checkboxfields">
The next three checkboxes are all named CBOX. The value shown is the value
specified in the INPUT tag.
</p>
<p>
Now we have a selection box, LBOX, that allows multiple selections.
</p>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
1 This element, along with elements 2 and 3, enables you to specify multiple values. The creation of multiple
value global macro variables and their usage is discussed in “Using Input Parameters with Multiple Values”
on page 27. The output shows the values for the macro variables created from these elements when the
default values are selected and the form is submitted.
2 This element enables you to specify multiple values.
3 This element enables you to specify multiple values.
4 The final SELECT tag creates a drop-down list that enables you to select the ODS style to apply to your
output. The HTMLBlue style is selected by default. The selected value is stored in the _ODSTYLE global
macro variable.
5 All macro variables are displayed in the output by default. Select the BLANKS check box to exclude macro
variables with blank values.
For the value of _PROGRAM, specify the path and name of the program to execute.
View the output to see the macro variables that are created when the form is submitted.
The HTML in this form has some of the same elements that are used in “ODS Output with Embedded Graphics”
on page 50. See that section for more information.
Program
* Declare input parameter;
%global BLANKS;
60
%macro blanks;
%if %length(&BLANKS) ne 0 %then and compress(value) ne ' ';
%mend;
*;
* Get the macro variables in the current SAS session.
* The RESOLVE function insures that the unmasked macro
* variable values are obtained.
*;
data work.globalvars
work.systemvars;
set work.vmacro;
where (name ne 'TCPLISTN' %BLANKS) and
(name not like '_RR_%') and
(name not like 'SQL%') and
(name not like 'SYS_SQL%');
by scope name;
length full_value $32767;
retain full_value;
keep name full_value;
if (first.name)
then full_value=value;
else full_value=cats(full_value, value);
run;
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return HTML output to the web browser because ods_html5 is specified as the value for the _OUTPUT_TYPE
input parameter. An ODS statement for the HTML5 destination is also issued.
The ODS HTML5 destination is used because it is the most up-to-date destination for creating HTML output.
The HTML is written to the _WEBOUT FILEREF assigned by the %JESBEGIN macro, and the style specified in
the _ODSSTYLE input parameter controls the appearance of the output.
The BLANKS macro generates code to omit blank macro variables from the output, if this option was selected in
the input form.
Macro variable information spans multiple records in the SASHELP.VMACRO view when the value exceeds 200
characters. The DATA step code collects information from multiple records and then stores the first 32,767
characters of the value.
The HTMLENCODE function is used when resolving the full value to prevent execution of malicious code in the
web browser.
The PRINT procedure displays the global and system macro variable names and values.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
Output
The following HTML output is one representation of the variety of formats that ODS can produce.
62
<!DOCTYPE html>
<html lang="en">
<head>
<title>Multiple Output Formats</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<p>
This sample shows different output formats supported by the
Output Delivery System (ODS). Sample data sets can be printed
to any of the output formats listed below.
</p>
<hr/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
65
1 The first SELECT tag creates a drop-down list with the names of the data set to be displayed, and the first
item is selected by default. A macro variable named DATASET is created with the corresponding value in the
VALUE attribute of the OPTION tag when you select an item. The first and last items are used to test the
cases when no data set is specified and when a non-existent data set is selected, respectively. The SAS
program handles these two error conditions.
2 The second SELECT tag creates a drop-down list that enables you to select the ODS output format. The first
item is selected by default and results in a blank value for the _OUTPUT_TYPE macro variable. The SAS
program handles this case, and the ODS HTML5 destination creates the output.
3 The final SELECT tag creates a drop-down list that enables you to choose the ODS style to apply to your
output. The HTMLBlue style is selected by default. The selected value is stored in the _ODSSTYLE global
macro variable.
The following table contains the display values for the first drop-down list and the values for the DATASET global
macro variable:
blank blank
SASHELP.RETAIL sashelp.retail
SASHELP.CLASS sashelp.class
SASHELP.REVHUB2 sashelp.revhub2
does_not_exist does_not_exist
The following table contains the display values for the first drop-down list and the values for the
_OUTPUT_TYPE global macro variable:
(default)
HTML ods_html
HTML5 ods_html5
RTF_Tagset ods_tagsets.rtf
LaTeX ods_latex
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but only the _ODSDEST and DATASET variables are used by the program:
_ACTION execute
The _ODSDEST macro variable is derived from the value of _OUTPUT_TYPE and indicates the ODS
destination that is used.
The HTML in this form uses some of the same fields as “Simple ODS HTML” on page 46. See that section for
more information.
Program
* Declare input parameter;
%global DATASET;
%macro setup;
%if (%qcmpres(&DATASET) eq )
%then %let ERRORTEXT=ERROR: You must specify a data set.;
%else %if not %sysfunc(exist(&DATASET))
%then %let ERRORTEXT=ERROR: Data set ""%sysfunc(htmlencode(&DATASET))""
not found.;
%* Close the currently open destination and write message to the browser;
%let RC=%sysfunc(fdelete(_webout));
67
title;
data _null_;
abort cancel;
run;
%end;
%mend setup;
%SETUP
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return the type of output that is specified in the _OUTPUT_TYPE input parameter to the web browser.
An ODS statement for the appropriate destination is also issued. If a blank value is specified for the
_OUTPUT_TYPE input parameter, then a FILENAME statement for HTML output is issued, and the ODS
HTML5 destination is used. The ODS HTML5 destination is used because it is the most up-to-date destination
for creating HTML output.
ODS writes the output to the _WEBOUT FILEREF assigned by the %JESBEGIN macro, and the style specified
in the _ODSSYLE input parameter controls the appearance of the output.
The SETUP macro checks the validity of the value specified for the DATSASET input parameter. If no value is
specified or if the specified table does not exist, then an error message is created and returned to the web
browser using the HTML5 ODS destination. The HTMLENCODE function is used here, and later in the TITLE
statement, to prevent execution of malicious code in the web browser.
All ODS destinations are closed, and the current content of the _WEBOUT FILEREF is deleted to ensure that
only the error message is returned to the web browser. A FILENAME statement is issued to return HTML output
to the web browser, and an ODS statement for the HTML5 destination writes the error message to the
_WEBOUT FILEREF. See “Assigning a FILEREF for HTML Output” on page 33 for more information about this
type of FILENAME statement. No additional program statements are executed after the ABORT statement
executes.
The PRINT procedure displays the data in the specified table.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
HTML and PDF output are displayed by the web browser, and all other output is downloaded so that it can be
saved and opened with an appropriate application.
68
Upload a File
This example uploads an arbitrary file to the server and then displays information about the file. An HTML input
form, which enables you to select a file to upload, provides a basic user interface to the program.
Output
The following output is an example of a file that could be uploaded.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Upload a File</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<h1>Upload a File</h1>
<p>
Use this page to upload a file from your local
machine to the SAS server machine. The program displays
the macro variables with information about the file.
</p>
<p>
Optionally, you can choose to download the file from the
SAS server machine by clicking a link in the output.
</p>
70
<hr/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
1 When you upload a file, be sure to specify the METHOD and ENCTYPE attributes exactly as shown.
2 When you make a POST request, you must specify the _CSRF input tag exactly as shown. This tag ensures
the request is considered non-malicious by sending a Cross-Site Request Forgery token to the server.
3 A special form of the INPUT tag displays a file selector dialog box when you click a button. Navigate to the
file that you want to upload, select it, and then run the code. The file is transferred to the SAS server and
stored in the SAS Infrastructure Data Server using the Files service.
For the value of _PROGRAM, specify the path and name of the program to execute.
The HTML in this form has some of the same elements and features of the form used in “Simple ODS HTML” on
page 46. See that section for more information.
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but they are not used by the program:
_ACTION execute
_ODSDEST html5
_ODSSTYLE HTMLBlue
71
_OUTPUT_TYPE ods_html5
The _ODSDEST macro variable is derived from the value of _OUTPUT_TYPE and indicates the ODS
destination that is used.
Additional macro variables with information about the uploaded file are created. See the Output and Program
Description sections for more information.
Program
* Create a data set with information about the upload;
data work.upload_info;
varname = '_WEBIN_CONTENT_LENGTH';
value = symget('_WEBIN_CONTENT_LENGTH');
description = 'Specifies the size of the file that was uploaded in bytes
(supplied automatically by the Web browser).';
output;
varname = '_WEBIN_CONTENT_TYPE';
value = resolve(symget('_WEBIN_CONTENT_TYPE');
description = 'Specifies the content type that corresponds to the file that was uploaded
(supplied automatically by the Web browser).';
output;
varname = '_WEBIN_FILE_COUNT';
value = symget('_WEBIN_FILE_COUNT');
description = 'Specifies the number of files that were uploaded.';
output;
varname = '_WEBIN_FILEEXT';
value = resolve(symget('_WEBIN_FILEEXT');
description = 'Specifies the extension of the file that was uploaded.';
output;
varname = '_WEBIN_FILENAME';
value = resolve(symget('_WEBIN_FILENAME');
description = 'Specifies the name and original location of the file that was uploaded.';
output;
varname = '_WEBIN_FILEURI';
value = resolve(symget('_WEBIN_FILEURI');
description = 'Specifies the URI of the location of the uploaded file';
output;
72
varname = '_WEBIN_NAME';
value = resolve(symget('_WEBIN_NAME');
description = 'Specifies the value that corresponds to the NAME attribute of the INPUT tag.';
output;
run;
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return HTML output to the web browser because ods_html5 is specified as the value for the _OUTPUT_TYPE
input parameter. An ODS statement for the HTML5 destination is also issued.
The ODS HTML5 destination is used because it is the most up-to-date destination for creating HTML output.
The HTML is written to the _WEBOUT FILEREF assigned by the %JESBEGIN macro, and the HTMLBLUE
style, specified in the _ODSSTYLE input parameter, controls the appearance of the output.
Additional global macro variables with information about the file are created as part of the upload process. This
information is retrieved and stored in the WORK.UPLOAD_INFO table.
The _WEBIN_FILEURI macro variable is of special interest because it provides a reference to the temporary
location of the uploaded file. This location is associated with the job execution object and deleted when the job
expires.
The FOOTNOTE statement shows an example of downloading the file by adding /content to the end of the
_WEBIN_FILE_URI macro variable. The “Upload a CSV File” on page 72 provides an example of referencing
the uploaded file using a FILENAME statement.
The PRINT procedure displays information about the uploaded file.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
Output
The following output is an example of a CSV file that could be uploaded.
73
<!DOCTYPE html>
<html lang="en">
<head>
<title>Upload a CSV File</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<p>
Use this page to upload a CSV file from your local
machine to the SAS server machine. The program imports the
file into a SAS table and then uses PROC PRINT to display the
first 10 records.
</p>
<p>
Optionally, you can choose to download the file from the
SAS server machine by clicking a link in the output.
</p>
<hr/>
<br/>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
This input form is functionally equivalent to the form used in “Upload a File” on page 68.
The file that you choose to upload should be a CSV file with the .csv file extension.
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but they are not used by the program:
_ACTION execute
_ODSDEST html5
_ODSSTYLE HTMLBlue
_OUTPUT_TYPE ods_html5
Additional macro variables with information about the uploaded file are created. See “Upload a File” on page 68
for more information.
Program
* Check the file extension to verify that it is a CSV file;
data _null_;
length filename $1024;
filename = htmlencode(strip("&_WEBIN_FILENAME"));
call symputx('_WEBIN_FILENAME', filename);
if (upcase("&_WEBIN_FILEEXT") ne 'CSV') then do;
rc = dosubl('ods all close;');
file _webout;
put '<!DOCTYPE html>';
put '<html lang="en">';
put '<head><title>Program Error</title></head>';
put '<body role="main">';
put '<h1>ERROR: Uploaded file "' filename +(-1) '" is not a CSV file.</h1>';
put '</body>';
put '</html>';
abort cancel;
end;
run;
76
Program Description
The %JESBEGIN macro performs several tasks before executing the code. A FILENAME statement is issued to
return HTML output to the web browser because ods_html5 is specified as the value for the _OUTPUT_TYPE
input parameter. An ODS statement for the HTML5 destination is also issued.
The ODS HTML5 destination is used because it is the most up-to-date destination for creating HTML output.
The HTML is written to the _WEBOUT FILEREF that is assigned by the %JESBEGIN macro, and the
HTMLBLUE style, specified in the _ODSSTYLE input parameter, controls the appearance of the output.
Additional macro variables with information about the uploaded file are created during the upload process. See
“Upload a File” on page 68 for more information.
The HTMLENCODE function encodes the values of input parameters to prevent execution of malicious code in
the web browser.
If the value of the _WEBIN_FILEEXT macro variable indicates that a CSV file was not uploaded, then action is
taken to prevent further code execution. The DOSUBL function closes all open ODS destinations, and an error
message is returned to the web browser. No additional program statements are executed after the ABORT
statement executes.
The FILENAME statement creates a reference to the temporary location of the uploaded file. The file can be
used with PROC IMPORT or with any other code that accepts a FILEREF. For example, you can use the
FCOPY function to make a copy of the file.
PROC IMPORT creates the WORK.MYDATA table from the uploaded CSV file.
The PRINT procedure displays the first 10 records of the SAS table that is created by the IMPORT procedure,
and a link to download the CSV file is created by the FOOTNOTE statement.
The %JESEND macro executes after the last line of code and closes all open ODS destinations.
77
Output
HTML Input
<!DOCTYPE html>
<html lang="en">
<head>
<title>Report with Download Links</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<p>
The PRINT procedure displays data in the SASHELP.CLASS table in HTML format. Links are provided
to download the output in the Excel and PDF formats.
</p>
</select>
<br/>
<br/>
<hr/>
</form>
</body>
</html>
The HTML in this form uses some of the same fields as “Simple ODS HTML” on page 46. See that section for
more information.
For the value of _PROGRAM, specify the path and name of the program to execute.
The FILENAME and ODS statements issued by the %JESBEGIN macro do not meet the needs of this program.
Specifying none for _OUTPUT_TYPE suppresses the issuing of these statements. The appropriate statements
are issued within the program.
When the form is submitted, the following global macro variables are defined just before SAS code execution,
but only _ODSSTYLE is used by the program:
_ACTION execute
_ODSDEST blank
_OUTPUT_TYPE none
Program
* Close all open destinations;
%global _ODSSTYLE;
ods escapechar='^';
proc format;
value $gender 'F' = 'Female'
'M' = 'Male';
run; quit;
proc sql;
create view work.class as
select name label = 'Name',
sex label = 'Gender' format=$gender.,
age label = 'Age',
height label = 'Height',
weight label = 'Weight'
from sashelp.class
order by sex;
quit;
* Create the Excel XML and PDF output and associate with the job;
1 The ODS DOCUMENT statement stores the output components from the PRINT procedure in a document
named MYDOC. You can later use PROC DOCUMENT to display the results using any ODS destination.
This technique is useful when you need to display procedure output several times, but you do not want to
rerun the procedure.
2 FILENAME and ODS statements are not issued by the %JESBEGIN macro because _OUTPUT_TYPE=none
is specified. FILENAME statements are issued to store the Microsoft XML results and the PDF results,
following the general format discussed in “Assigning a FILEREF for Other Types of Output” on page 34.
3 The next FILENAME statement stores PDF output generated by the ODS PDF destination. The
CONTENTTYPE option creates a MIME header that informs the web browser that the content is intended for
a client capable of rendering PDF output. Most web browsers can display PDF output, so the
CONTENTDISP option is not needed.
4 As discussed in “Assigning a FILEREF for HTML Output” on page 33, the FILESRVC access method creates
global macro variables of the form _FILESRVC_fileref_URI, where FILEREF is the fileref used in the
FIENAME statement. This macro variable provides a relative URL that can be used to reference and retrieve
the file using the Files service. These macro variables are used to create the EXCEL_LINK and PDF_LINK
macro variables. Later they are used to create download links.
5 A FILENAME statement is issued to return HTML content to the web browser. See “Assigning a FILEREF for
HTML Output” on page 33 for more information about this statement.
6 The ODS HTML5 destination creates the HTML output using the ODS style specified in the _ODSSTYLE
input parameter. The macro variables created earlier provide download links to the Excel XML and the PDF
versions of the report. The NBSPACE inline formatting function provides extra blank space between the link
text in the output. See SAS Output Delivery System: User’s Guide for more information about the NBSPACE
inline formatting function.
82
Program Description
The %JESBEGIN macro normally performs several tasks before executing your code. In this case, only a list of
global macro variables is displayed because _OUTPUT_TYPE=none is specified.
See SAS Output Delivery System: User’s Guide for more information about ODS ESCAPECHAR.
The SQL procedure selects the data of interest, applies a user-defined format, and then sorts the data.
PROC DOCUMENT executes and replays the PROC PRINT output created earlier and stores it in the XML and
PDF files. The ODS destinations are closed after PROC DOCUMENT creates the output files. See SAS Output
Delivery System: Procedures Guide for more information about PROC DOCUMENT.
PROC DOCUMENT then executes and replays the PROC PRINT output created earlier, and the HTML output is
displayed in the web browser. The %JESEND macro executes after the last line of code, but it does not close all
open ODS destinations because _OUTPUT_TYPE=none is specified. The HTML5 destination must be explicitly
closed.
Simple JSON
This example uses PROC JSON to display the SASHELP.CLASS table in JSON format. Use this technique and
execute the job using direct URL access if you have an application that requires data in JSON format. An HTML
input form provides a basic user interface to the program.
Output
[
{
"Name": "Alfred",
"Sex": "M",
"Age": 14,
"Height": 69,
"Weight": 112.5
},
{
"Name": "Alice",
"Sex": "F",
"Age": 13,
"Height": 56.5,
"Weight": 84
},
{
"Name": "Barbara",
"Sex": "F",
"Age": 13,
"Height": 65.3,
"Weight": 98
}, ...
]
<!DOCTYPE html>
<html lang="en">
<head>
<title>Simple JSON</title>
<style type="text/css">
.pointer {
cursor: pointer;
}
</style>
</head>
<body role="main">
<h1>Simple JSON</h1>
<p>
The JSON procedure creates simple JSON content that returns the data in the SASHELP.CLASS table.
</p>
<hr/>
</form>
</body>
</html>
The HTML in this form uses some of the same fields as “Simple ODS HTML” on page 46. See that section for
more information.
For the value of _PROGRAM, specify the path and name of the program to execute.
The value of _OUTPUT_TYPE indicates that non-ODS JSON output is created by the job. The %JESBEGIN
macro issues a FILENAME statement that supports JSON output.
Program
proc json out=_webout nosastags pretty;
export sashelp.class;
run; quit;
Program Description
The %JESBEGIN macro assigns a FILENAME statement to return JSON output to the web browser because
json is specified as the value for the _OUTPUT_TYPE input parameter.
The JSON procedure converts the SASHELP.CLASS table to JSON format and then writes JSON data to the
_WEBOUT FILEREF that is assigned by the %JESBEGIN macro. The JSON is displayed by the web browser.
The %JESEND macro executes after the last line of code, but it does not close all open ODS destinations
because this sample does not use ODS.
This technique is useful if you have an application such as a JavaScript grid or chart object that requires data in
JSON format. In your application, specify the following URL to retrieve the data in JSON format:
http://host:port/SASJobExecution/?_program=/Folder/Simple JSON&_action=execute
Use the concepts in this example if your application requires data in another format, such as XML or CSV.
Reference
_DEBUG Any valid value for _DEBUG If one of the values for _DEBUG is
trace, then MPRINT is turned on, LS
is set to max, and additional debug
messages are printed in the log.
_ENCODING Any valid SAS encoding Specifies a value for the ENCODING
option in the ODS statement.
_FILEREF_OPTIONS Any valid value for the FILESRVC Specifies a value to add to the end of
FILENAME statement the FILENAME statement.
_GOPT_DEVICE Any valid value for the DEVICE Specifies a value to add to a
graphic option GOPTIONS statement.
_GOPT_HSIZE Any valid value for the HSIZE graphic Specifies a value to add to a
option GOPTIONS statement.
_GOPT_VSIZE Any valid value for the VSIZE graphic Specifies a value to add to a
option GOPTIONS statement.
_GOPT_XPIXELS Any valid value for the XPIXELS Specifies a value to add to a
graphic option GOPTIONS statement.
_GOPT_YPIXELS Any valid value for the YPIXELS Specifies a value to add to a
graphic option GOPTIONS statement.
_ODS_DEVICE Any valid graphics device Specifies a value for the OUTPUTFMT
option of the ODS GRAPHICS
statement.
_ODSOPTIONS Any valid ODS options Specifies a value to add to the ODS
statement.
_ODSSTYLE Any valid ODS style Specifies a value for the STYLE option
in the ODS statement.
_JOBERROR 0 for success, nonzero for failure Indicates whether the %JESBEGIN
macro executed successfully
_ODSDEST Value to the right of ods_ in the value Specifies which ODS destination is
of the _OUTPUT_TYPE parameter used, if any
_RMTADDR Specifies the Internet Protocol (IP) address of the client that
sent the request.
_RMTHOST Specifies the fully qualified name of the client that sent the
request or the IP address of the client if the name cannot be
determined.
_URL Specifies the URL of the web server middle tier that is used
to access the job.
_USERLOCALE Specifies the locale for the user that was set in the user
preferences. If this value was not set, it contains the locale
sent in the HTTP request Accept-Language header.
_XFORWARD Specifies the host and port of the original HTTP request.
89
_WEBIN_FILE_COUNT
_WEBIN_FILEEXT
_WEBIN_FILENAME
_WEBIN_FILEURI
_WEBIN_NAME
Value Description
wait Displays a wait screen with informational text while the job
is executing. This value works only when _ACTION is used
as a URL parameter.
90
PARAM_LIST Macro
The param_list macro is used to convert the parameter list generated by a multiple–value prompt into a form that
is useful in your SAS code.
Arguments
Name Description
mvar Required. Specifies the name of the macro variable that corresponds to the prompt
name.
outvar Optional. Specifies the name of the macro variable that contains the converted
parameter list. If the name is not specified, an underscore (_) is added to the beginning
of the value specified in mvar.
dlm Optional. Specifies a character that is used to delimit values in the converted parameter
list. A blank space is used by default. If a character is specified, the delimiter followed by
a blank space is used.
quote Optional. Specify y (case-insensitive) to quote the individual values in the converted
parameter list. By default, the value is n.
The value of the macro variable specified in the OUTVAR argument is valid when one or more values are
selected in the prompt. If no values are selected, then the macro variable is assigned a blank value.
The code fails if the prompt_vals macro variable is blank because the column_list macro variable does not have
a value. This might happen if no values were selected in the prompt. One way to avoid this problem is to use the
IFC function:
proc print data=sashelp.class;
%sysfunc(ifc(%sysfunc(length(&COLUMN_LIST)) gt 0,
"var &COLUMN_LIST",
));
run; quit;
proc sql;
create table work.class as
91
select &COLUMN_LIST
from sashelp.class;
run; quit;
See the previous example for information about handling missing prompt values.
This example assumes that a prompt is used to select M, F, or both values (case–sensitive). Specify y for the
quote argument because the values of character variables must be quoted:
%param_list(mvar=prompt_vals, outvar=value_list, dlm=%str(,), quote=y)
Source Code
%macro param_list(mvar=, outvar=, dlm=, quote=n);
%local I PARAMLIST;
%let QUOTE=%upcase("E);
92
%if (%bquote(&OUTVAR) eq )
%then %let OUTVAR = _&MVAR;
%global &OUTVAR;
%global &MVAR.0;
%let &OUTVAR=&PARAMLIST;
%exit:
%mend param_list;
General
The General section includes settings that enable users to change the appearance of the web application,
enable warning and confirmation messages to be displayed, and choose a profile picture. Here are the settings:
n You can change the appearance of the web application by using the Theme setting. The default theme is set
by the system administrator. The theme specifies the collection of colors, graphics, and fonts that appear in
the application. You can choose from SAS themes or custom themes, if available.
93
Select Choose a theme, and then select another theme from the drop-down list to change the look of the
applications. The theme changes after you close the Settings window.
SAS themes:
Illuminate
This theme has a clean and uncomplicated color palette that is easy to use.
Inspire
This theme consists of vibrant and cohesive colors that shift the emphasis from the application to the
content.
High Contrast
This theme presents a dark background with high-contrast foreground elements to meet the needs of
users with low vision.
n If you want messages to display that you previously asked not to display, click Reset Messages. By default,
all warnings and confirmation messages are displayed.
n You can select a profile picture to display as an avatar in the application bar, as well as in other places within
the application that use avatars. An avatar is the graphical representation of the user or the user's alter ego
or character.
Click Choose Picture and then select an image file to upload. The image file’s size can be up to 1 MB. The
valid file types are BMP, GIF, JPEG, JPG, and PNG.
Accessibility
Several settings in the Accessibility section can assist people who rely on assistive technologies:
n Select Enable sounds to hear audio indicators for events that occur within the user interface.
n Select Enable visual effects to show visual effects that indicate state changes. For example, when this
setting is enabled, you see a subtle movement in the user interface if you delete an item.
n Select Invert application colors to make the user interface easier to see for users with sensitivity to certain
bright colors (for example, a black-on-white display). You can also use the Ctrl+` (Ctrl+back quote) keyboard
shortcut to invert the application colors.
n The focus indicator is an outline that indicates which user interface component is active. You can make the
focus indicator easier to see by selecting Customize the focus indicator settings and adjusting the color,
thickness, and opacity.
Landmarks are references to the primary areas of an application’s user interface. They provide a quick and easy
way for keyboard users to navigate to these areas of the application. You can access a list of landmarks by
using one of the following keyboard shortcuts:
n For Microsoft Windows, press Ctrl+F6.
94
Use the arrow keys to select a landmark, and then press Enter to navigate to that area of the application.
SAS® and all other SAS Institute Inc. product or service names are registered trademarks or
trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration. Other
brand and product names are trademarks of their respective companies. Copyright © 2018, SAS
Institute Inc., Cary, NC, USA. All Rights Reserved. January 2019 2.0-P1:jobexecug