Discover Method

Overview of the Discover Method

The Discover method retrieves information, such as stored process metadata or a list of available data sources, from the SAS Metadata Repository. The Discover method returns a list of all the stored processes that have the keyword "XMLA Web Service" on the SAS Metadata Server. The SAS Stored Process Server is not invoked to service the Discover call.

Here is the syntax for the Discover method:

Discover (
   [in] RequestType As EnumString,
   [in] Restrictions As Restrictions,
   [in] Properties As Properties,
   [out] Result  As Rowset)

RequestType

Overview of RequestType

RequestType is a required parameter for the Discover method. The value of RequestType is an enumeration value that corresponds to a return rowset. The RequestType parameter specifies the type of information to be returned by the Discover request.

There are two main request types that are normally used with SAS BI Web Services: DISCOVER_DATASOURCES and STOREDPROCESS_PARAMETERS. DISCOVER_DATASOURCES and STOREDPROCESS_PARAMETERS both return a list of the stored processes that can be invoked. DISCOVER_DATASOURCES is a standard XMLA request type that returns a list of available data sources for the server or Web service so that you can select a data source with which to connect. The information that is returned by the DISCOVER_DATASOURCES request type includes the following information:

the name and a description of the data source
a URL to connect to the data source, the name, and data type of the provider
the type of security mode that the data source uses, as well as any additional information that is needed to connect to the data source

STOREDPROCESS_PARAMETERS is a request type that is specific to SAS. This request type returns a list of all the available stored processes along with a list of the parameters that are specified in each stored process.

Other request types that might be useful with SAS BI Web Services are DISCOVER_PROPERTIES and DISCOVER_SCHEMA_ROWSETS. DISCOVER_SCHEMA_ROWSETS returns a list of all the available request types along with their enumeration values and other information. For more information about what the DISCOVER_PROPERTIES request type returns, see Properties.

Note: Although the SAS XMLA Stored Process provider supports the DISCOVER_KEYWORDS, DISCOVER_LITERALS, and DISCOVER_ENUMERATORS request types, these request types are not useful for calling stored processes.

DISCOVER_DATASOURCES

The SAS BI Web Service returns one data source for each stored process that has been defined in the metadata for use with Web services.

For each returned stored process, the returned rowset contains:

DataSourceName

specifies the name of the stored process, as specified in SAS Management Console. For example,

/Samples/Stored Processes/
   Sample: MEANS Procedure Web Service

DataSourceDescription

specifies the description of the stored process, as specified in SAS Management Console. For example,

(PROC MEANS Stored Process that can be invoked by
   the SAS BI Web Services for Java middle tier.)

URL

specifies the URL to invoke the XMLA methods. This is usually the same as the URL that is used to invoke this Discover method. For example,

http://host:port/SASBIWS/services/XMLA

DataSourceInfo

specifies which data source to use. The SAS Stored Process Server data source is "Provider=SASSPS;".

ProviderName

specifies the provider behind the data source. For the SAS Stored Process Server, this is the SAS XML for Analysis Stored Process Provider.

ProviderType

specifies the type of provider that is behind the data source. The Stored Process Service supports only Tabular Data Provider.

AuthenticationMode

specifies the authentication required for the given data source (that is, indicates whether a user name and password are required). SAS BI Web Services for Java always return "Authenticated," meaning that you are required to authenticate to the SAS Metadata Repository whether you pass in credentials or use only default credentials that are configured by the administrator.

STOREDPROCESS_PARAMETERS

STOREDPROCESS_PARAMETERS is a custom request type that is used by the SAS Stored Process Service provider only. It returns metadata describing the parameters that are necessary to call the stored process. A stream parameter is always a required parameter and it never has a default. This does not mean that you are required to have a stream parameter for each stored process, but it means that any stream parameters that are defined for the stored process must be provided when the stored process is called using the Execute method.

For each returned stored process, the returned rowset contains:

StoredProcessName

specifies the name of the stored process.

Parameters

specifies a container that includes all of the parameters for the stored process.

Parameter

specifies a container that includes all of the details for a stored process parameter.

Name

specifies the name of the stored process parameter.

Description

specifies the description of the stored process parameter.

Type

specifies the parameter type. The possible parameter types for XMLA Web services are string, multi-line text, Boolean, integer, float, color, time, timestamp, and date. (XMLA Web services do not support advanced prompt types such as data source, data source item, OLAP member, data library, ranges, and prompts with multiple value types.) Note that all parameters are passed to SAS as macro variables, so the SAS program does not know the parameter type that is specified in the metadata. For more information about how to format parameter values, see Using Prompts with Generated Web Services.

Required

specifies whether the stored process parameter is required.

Default

specifies a default value for the stored process parameter.

Streams

specifies a container that includes all of the data sources for the stored process.

Stream

specifies a container that includes all of the details for a stored process data source.

The following is an example of a STOREDPROCESS_PARAMETERS response for a stored process that takes a single string and a single stream as input:

<row xmlns="urn:schemas-sas-com:xml-analysis:rowset">
   <StoredProcessName>
      /BIP Tree/copyintoout</StoredProcessName>
   <Parameters>
      <Parameter>
         <Name>inputname</Name>
         <Description>A simple string that we are
            passing as a parameter.</Description>
         <Required>true</Required>
         <Default />
         <Type>String</Type>
      </Parameter>
   </Parameters>
   <Streams>
      <Stream>
         <Name>instream</Name>
         <Description>This stream does allow
            multi-pass reads, so you do not have to
            use an XMLMap.</Description>
      </Stream>
   </Streams>
</row>

Restrictions

You can use the Restrictions parameter to filter which results get returned from a call to the Discover method. The restriction name specifies a column in a rowset that you restrict. The restriction value specifies which data to restrict in the column. Use the DISCOVER_SCHEMA_ROWSETS request type to get restriction information about the rowsets that are available in each request type. The DISCOVER_SCHEMA_ROWSETS request type returns a list of all the request types that are supported by the provider, along with restriction information and descriptions for each request type.

The Restrictions parameter is required in the Discover method, but it can be empty. Invalid values for restrictions are ignored.

The following RestrictionList element restricts a call to Discover STOREDPROCESS_PARAMETERS based on the name of the stored process:

<RestrictionList
   xmlns="urn:schemas-microsoft-com:xml-analysis">
   <StoredProcessName>
      /Samples/Stored Processes/
         Sample: MEANS Procedure Web Service
   </StoredProcessName>
</RestrictionList>

Properties

The Properties parameter enables you to specify properties of the Discover method, such as the return format of the result set or the time-out value.

Use the DISCOVER_PROPERTIES request type to get information about properties that are available for each request type and the values that are associated with those properties. The DISCOVER_PROPERTIES request type returns information about both standard and provider-specific properties. The returned information includes the name, description, data type, access, and current value of each property. The information also shows whether each property is required.

The following table contains a list of properties and property information, including sample values, that the DISCOVER_PROPERTIES request type returns. The value of PropertyType for each of these properties is string.

Values for the Properties Parameter

PropertyName	PropertyDescription	PropertyAccessType	Value
Content	Specifies the content of the XML result: None, Schema, Data, or Both.	ReadWrite	SchemaData
UserName	Specifies the user name to use for metadata authentication.	ReadWrite
Password	Specifies the password to use for metadata authentication.	Write
Domain	Specifies the domain to use for metadata authentication.	ReadWrite
ProviderName	Specifies the name of the XML for Analysis provider.	Read	SAS XML for Analysis StoredProcess Provider
ProviderVersion	Specifies the version of the XML for Analysis provider.	Read	1.0
Format	Specifies the format of the XML result: Tabular or Multidimensional.	Read	Tabular
DataSourceInfo	Specifies the identifying information that is required to retrieve data from a data source.	ReadWrite	Provider=SASSPS

You can list properties in any order. The Properties parameter is required in the Discover method. The only call to the Discover method that can have empty properties is DISCOVER_DATASOURCES. All other request types require at least DataSourceInfo to be specified, such as:

<PropertyList
   xmlns="urn:schemas-microsoft-com:xml-analysis">
   <DataSourceInfo>
      Provider=SASSPS
   </DataSourceInfo>
</PropertyList>

To cause a call to Discover to execute under a specific user's identity, a UserName and Password property can be included in the PropertyList element, such as:

<PropertyList xmlns="urn:schemas-microsoft-com:xml-analysis">
   <DataSourceInfo>
      Provider=SASSPS
   </DataSourceInfo>
   <UserName>username</UserName>
   <Password>password</Password>
</PropertyList>

If you choose to include the UserName or Password properties, it is important to ensure that access to your Web service is secure and encrypted. For more information, see the SAS Intelligence Platform: Web Application Administration Guide.

Result

The Result parameter is required. This parameter specifies the result set that the provider returns. The information that is returned can vary according to which values are used in the RequestType, Restrictions, and Properties parameters.