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

Details

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));

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 toPlatform 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 suited 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.

GRDSVC_ENABLE Function

Syntax

Required Argument

Optional Arguments

Details

See Also