Using Prompts with Generated Web Services

When defining stored process parameters, the prompt type definitions are mapped to web service schema. These schema mappings appear in the WSDL files for SOAP endpoints, but the type mappings still apply for other endpoints. You should use the same input XML for the plain XML endpoints as you do for the SOAP endpoints. However, you can omit the namespace prefixes and declarations for the plain XML endpoints. See Supported Types of Input and Output for XML and JSON Messages for more information about using prompts with these endpoint types.
The mapping of stored process prompt types to XML schema types is as follows:
How Prompt Types Map to Web Service Schema
Prompt Type
Parameter Type in Generated WSDL
Text, Date, Time, Color, Data source, File or directory, Data library
xs:string
Numeric
xs:int or xs:double
Ranges have lowerBound and upperBound elements
xs:type (where type is the appropriate value, such as int or dateTime, from this table)
xs:string (for lowerBound and upperBound elements)
Timestamp
xs:dateTime
Data source item has path and itemName elements
xs:string (for path and itemName elements)
OLAP member has label and uniqueName elements
xs:string (for label and uniqueName elements)
The xs: prefix in these values is an abbreviation for the namespace that is being used. This particular abbreviation stands for the standard XML schema namespace, http://www.w3.org/2001/XMLSchema. For more information about the XML schema, see http://www.w3.org/2001/XMLSchema.
For generated web services, the WSDL that is generated uses facets and restrictions that are based on prompt constraints. Values are validated against the constraints that are defined in metadata.
The following table explains how to format values for the various prompt types:
Guidelines for Entering Prompt Values (U.S. English Locale)
Prompt Type
Guidelines
Examples
Text
Enter any character value. Blank spaces and nonprintable characters can be used, but the value cannot consist completely of these characters. Trailing blanks are stored as part of the value and are included when the value is validated against the minimum and maximum length requirements.
  • you are here
  • eighty-five
  • Bob
Numeric
Enter a standard numeric value.
  • If you are working with an integer prompt, then do not use values with decimal places. If you use a value with zeros after the decimal point (for example, 1.00) for an integer prompt, then the zeros and the decimal point will be removed before the value is stored (for example, 1.00 will be stored as 1).
  • For prompts that allow floating-point values, the unformatted prompt value can contain up to 15 significant digits. Values with more than 15 significant digits of precision are truncated. Note that formatted values can have more than 15 significant digits.
  • 1.25
  • 6000
  • 2222.444
Date
For dates of type Day, enter values in one of the following formats:
  • ddmmmyyyy
  • ddmonth-nameyyyy (Java only)
  • mm/dd/yy<yy>
  • mm.dd.yy<yy>
  • mm-dd-yy<yy>
  • mmm/dd/yy<yy>
  • mmm.dd.yy<yy>
  • mmm-dd-yy<yy>
  • mmm dd, yyyy (Java only)
  • month-name/dd/yy<yy> (Java only)
  • month-name.dd.yy<yy> (Java only)
  • month-name-dd-yy<yy> (Java only)
  • month-name dd, yyyy
  • day-of-week, mmm dd, yy (Java only)
  • day-of-week, mmm dd, yyyy (Java only)
  • day-of-week, month-name dd, yy (Java only)
  • day-of-week, month-name dd, yyyy
  • yyyy/mm/dd (Java only)
  • yyyy.mm.dd (Java only)
  • yyyy-mm-dd (Java only)
  • yyyy.mmm.dd (Java only)
  • yyyy-mmm-dd (Java only)
  • yyyy.month-name.dd (Java only)
  • yyyy-month-name-dd  (Java only)
Here is an explanation of the syntax:
day-of-week
specifies either the first three letters of the day of the week or the full name of the day of the week. This value is not case sensitive.
dd
specifies a one-digit or two-digit integer that represents the day of the month.
mm
specifies a one-digit or two-digit integer that represents the month of the year.
mmm or month-name
specifies the first three letters of the full name of the month, or the full name of the month, respectively. This value is not case sensitive.
yy or yyyy
specifies a two-digit or four-digit integer that represents the year. To refer to a year that is more than 80 years in the past or 20 years in the future, use four digits. Valid values for a four-digit year range from 1600 to 2400.
  • 4APR1860
  • 14January1918
  • 12/14/45
  • 02.15.1956
  • 1–1–60
  • Oct/02/08
  • JUL.20.13
  • MAY-13–1924
  • Oct 05, 2006
  • February/10/00
  • March.1.2004
  • DECEMBER-25–08
  • SEPTEMBER 20, 2010
  • FRI, Jan 3, 20
  • Tuesday, Jan 15, 2008
  • Monday, January 16, 40
  • FRIDAY, JANUARY 04, 2008
  • 2041/5/13
  • 2050.07.25
  • 2100–1–1
  • 2009.NOV.02
  • 2400–Aug-8
  • 2101.December.31
  • 1919–APRIL-20
Date (cont’d.)
For dates of type Week, enter values in one of the following formats:
  • Www yy
  • Www yyyy (Java only)
  • Weekww yyyy
Here is an explanation of the syntax:
ww
specifies a one-digit or two-digit integer that represents the week of the year. Valid values range from 1 to 52.
yy or yyyy
specifies a two-digit or four-digit integer that represents the year. To refer to a year that is more than 80 years in the past or 20 years in the future, use four digits. Valid values for a four-digit year range from 1600 to 2400.
  • W1 08
  • W52 1910
  • Week 20 2020
  • Week 5 2048
For dates of type Month, enter values in one of the following formats:
  • mm/yy<yy>
  • mm.yy<yy>
  • mm-yy<yy>
  • mmm yy<yy> (Java only)
  • mmm/yy<yy>
  • mmm.yy<yy>
  • mmm-yy<yy>
  • month-name yy (Java only)
  • month-name yyyy
  • month-name/yy<yy> (Java only)
  • month-name.yy<yy> (Java only)
  • month-name-yy<yy> (Java only)
Here is an explanation of the syntax:
mm
specifies a one-digit or two-digit integer that represents the month of the year.
mmm or month-name
specifies the first three letters of the full name of the month, or the full name of the month, respectively. This value is not case sensitive.
yy or yyyy
specifies a two-digit or four-digit integer that represents the year. To refer to a year that is more than 80 years in the past or 20 years in the future, use four digits. Valid values for a four-digit year range from 1600 to 2400.
  • 12/1828
  • 06.65
  • 7–76
  • Jul 08
  • JUN/2010
  • SEP.20
  • Oct-2050
  • August 20
  • OCTOBER 1975
  • MARCH/1970
  • May.13
  • November-18
Date (cont’d.)
For dates of type Quarter, enter values in the following format:
  • quarter-name quarter yyyy
Here is an explanation of the syntax:
quarter-name
specifies the quarter of the year. Valid values are 1st, 2nd, 3rd, and 4th.
yyyy
specifies a four-digit integer that represents the year. Valid values for a four-digit year range from 1600 to 2400.
  • 1st quarter 1900
  • 4th quarter 2060
For dates of type Year, enter values in one of the following formats:
  • yy (Java only)
  • yyyy
Here is an explanation of the syntax:
yy or yyyy
specifies a two-digit or four-digit integer that represents the year. To refer to a year that is more than 80 years in the past or 20 years in the future, use four digits. Valid values for a four-digit year range from 1600 to 2400.
  • 1895
  • 86
  • 08
  • 2035
Time
Enter time values in the following format:
  • hh:mm<:ss> <AM | PM>
Here is an explanation of the syntax:
hh
specifies a one-digit or two-digit integer that represents the hour of the day. Valid values range from 0 to 24.
mm
specifies a one-digit or two-digit integer that represents the minute of the hour. Valid values range from 0 to 59.
ss (optional)
specifies a one-digit or two-digit integer that represents the second of the minute. Valid values range from 0 to 59. If this value is not specified, then the value defaults to 00 seconds.
AM or PM (optional)
specifies either the time period 00:01 to 12:00 noon (AM) or the time period 12:01 to 12:00 midnight (PM). If this value is not specified and you are using the 12-hour system for specifying time, then the value defaults to AM. Do not specify AM or PM if you are using the 24-hour system for specifying time.
  • 1:1
  • 1:01 AM
  • 13:1:1
  • 01:01:01 PM
  • 22:05
Timestamp
Enter timestamp values in the following format:
  • yyyy-mm-ddThh:mm:ss
Here is an explanation of the syntax:
yyyy
specifies a four-digit integer that represents the year. Valid values for a four-digit year range from 1600 to 2400.
mm
specifies a one-digit or two-digit integer that represents the month of the year.
dd
specifies a one-digit or two-digit integer that represents the day of the month.
hh
specifies a one-digit or two-digit integer that represents the hour of the day. Valid values range from 0 to 24.
mm
specifies a one-digit or two-digit integer that represents the minute of the hour. Valid values range from 0 to 59.
ss
specifies a one-digit or two-digit integer that represents the second of the minute. Valid values range from 0 to 59.
  • 2012-11-23T15:30:32
  • 2008-09-09T01:01:01
Color
Enter color values in one of the following formats:
  • CXrrggbb
  • 0xrrggbb
  • #rrggbb
Here is an explanation of the syntax:
rr
specifies the red component.
gg
specifies the green component.
bb
specifies the blue component.
Each component should be specified as a hexadecimal value that ranges from 00 to FF, where lower values are darker and higher values are brighter.
Bright red
  • CXFF0000
  • 0xFF0000
  • #FF0000
Black
  • CX000000
  • 0x000000
  • #000000
White
  • CXFFFFFF
  • 0xFFFFFF
  • #FFFFFF
Data source
Enter the name and location of a data source in the following format:
  • /folder-name-1/<.../folder-name-n/>data-source-name(type)
Here is an explanation of the syntax:
/folder-name-1/<.../folder-name-n/>
specifies the location of the data source.
data-source-name
specifies the name of the data source.
type
is the type of data source. The following values are valid unless otherwise noted: Table, InformationMap, and Cube. Use InformationMap for specifying either relational or OLAP information maps.
  • /Shared Data/Tables/OrionStar/Customers(Table)
  • /Users/MarcelDupree/My Folder/My Information Map(InformationMap)
  • /MyCustomRepository/More Data/Order_Facts(Table)
File or directory
Enter the name and location of a file or directory in the following format:
  • directory-specification<filename>
Here is an explanation of the syntax:
directory-specification
specifies the location of the file or directory in the file system of a SAS server.
filename
specifies the name of the file. This value is required only if the prompt is a file prompt. Depending on the operating environment that the SAS server runs in, you might need to put a forward slash (/) or a backslash (\) between the directory specification and the name of the file.
  • C:\Documents and Settings\All Users\Documents\myfile.txt
Data library
Enter the name and location of a data library in the following format:
  • /folder-name-1/<.../folder-name-n/>library-name(Library)
Here is an explanation of the syntax:
/folder-name-1/<.../folder-name-n/>
specifies the location of the library.
library-name
specifies the name of the library.
  • /Data/Libraries/Customer Data Library(Library)
  • /MyCustomRepository/More Data/OracleData(Library)
Data source item
For the path element, enter the path for a data source item in the following format:
  • /folder-name-1/<.../folder-name-n/>data-source-name(type)
Here is an explanation of the syntax:
/folder-name-1/<.../folder-name-n/>
specifies the location of the data source.
data-source-name
specifies the name of the data source.
type
is the type of data source. The following values are valid unless otherwise noted: Table or InformationMap. Use InformationMap for specifying either relational or OLAP information maps.
For the itemName element, enter the name for the data source item in the following format:
  • item-name
Here is an explanation of the syntax:
item-name
specifies the name of the data source item. This is the name of a column in a table or a data item in an information map.
path
  • /Shared Data/Tables/MYDATA(Table)
itemName
  • Year
OLAP member
For the uniqueName element, enter the name of the OLAP member.
For the label element, enter the label for the OLAP member.
uniqueName
  • PRICEAVG
label
  • Average Price
Note: An anonymous user cannot launch workspace servers. Dynamic prompt validation requires use of workspace servers if the user has been defined with an internal account. Thus, internal anonymous users will not be able to use all stored processes.
Prompt definitions in metadata provide a means to establish a contract between all parties that are involved in a web service request. SAS BI Web Services generate a WSDL and schema based on metadata definitions that provide a contract between the client and generated web service. Mature client programming tools can help assist clients in formulating valid SOAP requests. Web service endpoints also validate client input values via the SAS prompting framework. The SAS code that executes on the SAS server must be written in accordance to the metadata definitions that it represents. Otherwise, problems occur (for example, reading the wrong input parameter or expecting a different type) that result in SAS errors. If a SAS error occurs, then the generated web service returns a SOAP fault to the client for SOAP endpoints or HTTP errors for JSON and plain XML endpoints.