GRDSVC_ENABLE Function

Enables or disables one or all SAS sessions on a grid.

Valid in: %SYSFUNC or %QSYSFUNC Macro, DATA step
Category: Grid
Syntax
Required Argument
Optional Arguments
Details
See Also

Syntax

grdsvc_enable(identifier <,option-1; ... option-n> )
grdsvc_enable(identifier,"" | " )

Required Argument

identifier

specifies one or all server sessions to be enabled or disabled for grid execution. The identifier is specified as follows:

server-ID

specifies the name of a SAS/CONNECT server session to be enabled or disabled for grid execution.

You use this server-ID when you sign on to a server session using the SIGNON or the RSUBMIT statement. For information about ways to specify the server ID, see SAS/CONNECT User's Guide.
Requirement If the function is used in a DATA step, enclose server-ID in double or single quotation marks. A server-ID cannot exceed eight characters.

_ALL_

specifies that all SAS sessions are enabled or disabled for grid execution.

See SIGNON statement and RSUBMIT statement in SAS/CONNECT User's Guide
Example 
%let rc=%sysfunc(grdsvc_enable(grdnode1,server=SASApp));
%let rc=%sysfunc(grdsvc_enable(_all_,server=SASApp));
%let rc=%sysfunc(grdsvc_enable(notgrid1,""));

Optional Arguments

SASAPPSERVER=server-value

specifies the name of a SAS Application Server that has been defined in the SAS Metadata Repository. The SAS Application Server contains the definition for the logical grid server that defines the grid environment.

Alias SERVER=, RESOURCE=
Restriction Although a SAS Application Server is configured as a required grid resource in most environments, some grids are not partitioned by resource names. In these environments, passing the SAS Application Server name as a required resource causes the job to fail. To find out whether the SAS Application Server is designated as a required resource value or not in the SAS Metadata Repository, use the GRDSVC_GETINFO function call.
Interaction The name of the SAS Application Server is passed to Platform Suite for SAS as a resource value. When the job is executed, Platform Suite for SAS selects a grid node that meets the requirements that are specified by this value. If SAS-application-server contains one or more spaces, the spaces are converted to underscores before the name is passed to Platform Suite for SAS as a resource value.
Tip For Platform Suite for SAS, this server-value corresponds with the value of a resource that the LSF administrator has configured in the lsf.cluster.cluster-name file and the lsf.shared file on the grid-control server.
See GRDSVC_GETINFO Function to find out whether the SAS Application Server is designated as a required resource value in the SAS Metadata Repository. To remove the SAS Application Server name as a required resource, see Modifying SAS Logical Grid Server Definitions.
Example 
%let
rc=%sysfunc(grdsvc_enable(_all_, server=SASApp));

GRIDOPTSET=”grid_options_set_name”

specifies the grid options set to be used when running jobs on the grid. A grid options set is a collection of grid options, SAS options, and required resources that are associated with a particular SAS client application. The purpose of a grid options set is to enable a SAS grid administrator to define a collection of options in SAS metadata. These options will map to one or more SAS client applications and will be applied to workload submitted to the grid.

Requirements A grid options set must be defined in SAS Management Console before it can be used in the GRDSVC_ENABLE function.
The grid options set name must be enclosed in quotation marks.

WORKLOAD=workload-value

identifies the resource for the job to be executed on the grid. This value specifies an additional resource requirement for which Platform Suite for SAS selects the appropriate grid nodes.

The specified workload value should match one of the workload values that are defined in the SAS Application Server in the SAS Metadata Repository.
Requirement Workload values are case sensitive.
Interaction If workload-value contains one or more spaces, the spaces are converted to underscores before the value is passed to the grid provider. If workload-value is not located in the SAS Application Server definition and no other errors occur, a 0 result code is returned, and this note is displayed: 
NOTE: Workload value "gridResource" does not exist in 
the SAS Metadata Repository
.
Tip For Platform Suite for SAS, this workload-value corresponds with the resource that the LSF administrator has configured in the lsf.cluster.cluster-name file and the lsf.shared file on the grid-control computer.
Example 
%let
rc=%sysfunc(grdsvc_enable(grdnode1, server=SASApp;
workload=EM));
The workload value EM specifies the resource name. EM must be assigned to a grid node in order to process this job. An example is assigning EM to machines that can process SAS Enterprise Miner jobs.

JOBNAME=job-name-macro-variable

specifies the macro variable that contains the name that is assigned to the job that is executed on the grid.

Example 
%let
hrjob=MyJobName;
%let rc=%sysfunc(grdsvc_enable(grdnode1, server=SASApp; jobname=hrjob)); 
 signon grdnode1;
In this example, hrjob is the name of the macro variable to which the job name is assigned. The actual job name is MyJobName. The status of the job can be tracked using the SAS Grid Manager Plug-in for SAS Management Console. In this example, you track the status of the job named MyJobName.

JOBOPTS=job-opts-macro-variable

specifies the macro variable that contains the job options. The job option name/value pairs are assigned to job-opts-macro-variable.

The job options are used by the grid job to control when and where a job runs. Job options are specified as name/value pairs in this format:
option-1=value-1;option-2=“value-2 with spaces"; ...
option-n='value-n with spaces';
For a list of the job options that you can specify, see Supported Job Options.
Requirement Use a semicolon to separate job option and value pairs. For multiple values, use a macro quoting function for the semicolon or use single or double quotation marks to enclose all job options. If the value contains one or more spaces, tabs, semicolons, or quotation marks, enclose the value in single or double quotation marks.
Example 
%let
rc=%sysfunc(grdsvc_enable(all, server=SASApp; jobopts=hrqueue));
%let hrqueue=queue=priority%str(;)project="HR Monthly";
signon grdnode1;
%let hrqueue='queue=priority;project="HR Yearly"';
signon grdnode2
Both jobs are sent to the priority queue. The first job is associated with the project named “HR Monthly” and the second job is associated with the project named “HR Yearly.”

"" | "

disables grid execution for the specified server ID or all server sessions.

This value is intended to be used when you have specified _ALL_ in a previous call but you want to disable it for a small number of exceptions.
Requirement Double or single quotation marks can be used. Do not insert a space between the double or single quotation marks.
Interaction When quotation marks are used with _ALL_, it clears all previous grid settings that were specified using the GRDSVC_ENABLE function.
Example 
%let rc=%sysfunc(grdsvc_enable(grdnode1,""));
%let rc=%sysfunc(grdsvc_enable(_all_,''));

Details

The GRDSVC_ENABLE function is used to enable and disable a grid execution. Grid execution can be enabled for a specified SAS session or for all SAS grid sessions. If a grid environment is not configured or is unavailable, the job is started as a symmetric multi-processor (SMP) process instead.
The GRDSVC_ENABLE function does not resolve to a specific grid node, and it does not cause grid execution. The server ID is mapped to a specific grid node. The server session starts on the grid node when requested by subsequent SAS statements (for example, when the SIGNON statement or the RSUBMIT statement is executed).
In order to restrict the use of specific grid nodes to be used by server sessions, the name of the SAS Application Server and the workload resource value are passed as required resources to Platform Suite for SAS.
Note: An exception to this behavior is when the SAS Application Server is disabled as a required resource for the grid server. For details, see the restriction for the SASAPPSERVER= option.
The grid can be partitioned according to resource or security requirements. If grid nodes do not have the required resources, then SAS requests fail. If grid nodes have the required resources but are busy, SAS requests are queued until grid resources become available. For information, see Defining and Specifying Resources.
Some SAS applications are appropriate for execution in a grid environment, but not in an SMP environment. Such applications should contain a macro that checks the return code from the GRDSVC_ENABLE function to ensure that a grid node, rather than an SMP process, is used.
Here are the result codes:
GRDSVC_ENABLE Function Result Codes
Result Code
Explanation
2
Reports that one or all server sessions were disabled from grid execution.
1
Reports that a grid environment is unavailable due to one or more of these conditions:
  • A connection to the SAS Metadata Server is unavailable.
  • A logical grid server has not been defined in the SAS Metadata Repository.
  • The current user identity does not have authorization to use the specified logical grid server.
  • SAS Grid Manager has not been licensed.
Instead, server sessions execute on the multi-processor (SMP) computers as a SASCMD sign-on. One of these commands, in order of precedence, is used to start the server session:
  • the value of the SASCMD system option
  • !sascmd -noobjectserver
0
Reports that the specified session was enabled.
-1
Reports a syntax error in the function call. An example is the omission of the server ID.
-2
Reports a parsing error in the function call. An example is an invalid option.
-3
Reports an invalid server ID in the function call.
-5
Reports an out-of-memory condition while the function is executing.
-6
Reports that the function cannot connect to the SAS Metadata Server or cannot access the grid metadata information. This condition frequently occurs when the user is not explicitly defined in metadata. By default, users without a definition in metadata are assigned to the PUBLIC group, which is not granted the ReadMetadata permission.

See Also

SAS/CONNECT User's Guide
SAS/CONNECT User's Guide
SAS Language Reference: Dictionary
SAS Macro Language: Reference
Copyright © SAS Institute Inc. All rights reserved.