Skip to main content

%CSP.Response

class %CSP.Response extends %Library.RegisteredObject

The %CSP.Response class determines what the HTTP headers generated for this page will look like. Note that by default CSP pages are set to never be cached, so the browser will have to get the page each time. If you wish to change this see the Expires property.

Property Inventory

Method Inventory

Properties

property AllowOutputFlush as %Integer [ InitialExpression = 0 ];
This flag is intended to be used in conjunction with the Flush() method. The Flush() method will flush the response output buffer from InterSystems IRIS to the CSP Gateway. If this flag is set in the page OnPreHTTP() method, the Gateway will flush each buffer received from InterSystems IRIS to the web server, without attempting to aggregate small buffers into larger ones before final dispatch back to the web server.

Example: 
<script language="Cache" method="OnPreHTTP" arguments="" returntype="%Boolean">
: Set %response.AllowOutputFlush=1
: Quit 1
</script>
Property methods: AllowOutputFlushDisplayToLogical(), AllowOutputFlushGet(), AllowOutputFlushIsValid(), AllowOutputFlushLogicalToDisplay(), AllowOutputFlushNormalize(), AllowOutputFlushSet()
property CharSet as %String;
Sets the Character Set for the content-type header. If CharSet is '= "" and NoCharSetConvert=0, then output is translated for any content-type. If not specified for text, then default is utf-8 on Unicode systems and the system default on 8-bit systems.
Property methods: CharSetDisplayToLogical(), CharSetGet(), CharSetIsValid(), CharSetLogicalToDisplay(), CharSetLogicalToOdbc(), CharSetNormalize(), CharSetSet()
property ContentLength as %String;
Sets the Content-Length header. Since the HTTP headers are sent after the OnPreHTTP() method is complete, setting it after this has no effect.
Property methods: ContentLengthDisplayToLogical(), ContentLengthGet(), ContentLengthIsValid(), ContentLengthLogicalToDisplay(), ContentLengthLogicalToOdbc(), ContentLengthNormalize(), ContentLengthSet()
property ContentType as %String [ InitialExpression = "text/html" ];
Sets the Content-Type header. Since the HTTP headers are sent after the OnPreHTTP() method is complete, setting it after this has no effect.
Property methods: ContentTypeDisplayToLogical(), ContentTypeGet(), ContentTypeIsValid(), ContentTypeLogicalToDisplay(), ContentTypeLogicalToOdbc(), ContentTypeNormalize(), ContentTypeSet()
property Context as %String [ MultiDimensional ];
Maintain a list of name-value pairs that will be added to every hyperlink and form on this page. This array should be created in the OnPreHTTP() method before the page is being rendered or some links will have these parameters and some will not. This can be used for example to add a page Id to every link from this page so that if the user bookmarks this page and comes back to it later you will know they clicked on a link from the 'Camera purchase' page of the web site.

The format of this array is just: 

  Set %response.Context("Name")="Value"
Note that if the page you link to is encoded then these parameters will be automatically encrypted, if you do not want this behavior then 'Set %response.Context("Name","encrypted")=0' in addition to setting the value of this property. If you wish to insert the same item name multiple times you can do this.

  Set %response.Context("Name")="Value"
  Set %response.Context("Name",1)="Value2"
This will insert 'Name' twice, first with 'Value' and then with 'Value2'.
Property methods: ContextDisplayToLogical(), ContextGet(), ContextIsValid(), ContextLogicalToDisplay(), ContextLogicalToOdbc(), ContextNormalize(), ContextSet()
property CookiePath as %String (MAXLEN = 256);
The path we will send the session cookie with
Property methods: CookiePathDisplayToLogical(), CookiePathGet(), CookiePathIsValid(), CookiePathLogicalToDisplay(), CookiePathLogicalToOdbc(), CookiePathNormalize(), CookiePathSet()
property Cookies as %String [ MultiDimensional ];
Maintains the collection of cookies to be sent out. See SetCookie().
Property methods: CookiesDisplayToLogical(), CookiesGet(), CookiesIsValid(), CookiesLogicalToDisplay(), CookiesLogicalToOdbc(), CookiesNormalize(), CookiesSet()
property Domain as %String;
The %response.Domain attribute is used as the default domain for csp:text, span and div tags. The %response.Domain attribute is initialized from the DOMAIN parameter of the CSP and may be changed by the page class at any time.
Property methods: DomainDisplayToLogical(), DomainGet(), DomainIsValid(), DomainLogicalToDisplay(), DomainLogicalToOdbc(), DomainNormalize(), DomainSet()
property Expires as %String [ Calculated ];
Used to control the expiration of the CSP page being served. It can be set to one of the following values:
  • -1: Expire immediately, this is the default for a CSP page
  • 0: Expire immediately, this also sets the 'no-store' option so using the back button will request a new page
  • "": No HTTP 'Expires', 'Pragma', or 'cache-control' headers are sent.
  • nnnnn: Number of seconds from now when the object should expire
  • Thu, 29 Oct 1998 17:04:19 GMT: Absolute time at which the object should expire
  • One way to 'never expire' is to set a 'forever date':
  • "Sun, 17-Jan-2038 19:14:07 GMT" is the maximum 32-bit Unix time/date
  • "Mon, 31 Dec 2035 12:00:00 GMT" is the maximum IIS6 date.
  • ddddd,sssss: Absolute time the object should expire in $ZTimeStamp format. Note that this must be specified in the GMT timezone
Note that setting this header also effects the 'Cache-Control' and 'Pragma' headers. If the page is set to expire immediately then it will send a 'Cache-Control: no-cache' and 'Pragma: no-cache' to prevent any caches from storing the page. If the page is set to never expires then it will not send any 'Cache-Control' or 'Pragma' headers. If you set an expires date then it will not modify the 'Cache-Control' or 'Pragma' headers so if they are set they will be sent as specified and if you did not set them then nothing will be sent for these headers.
Property methods: ExpiresDisplayToLogical(), ExpiresIsValid(), ExpiresLogicalToDisplay(), ExpiresLogicalToOdbc(), ExpiresNormalize()
property GzipOutput as %Boolean;
If true the ask the CSP gateway to gzip the output and add modify the HTTP header to show the data is gzipped. Depending on the version and platform of the CSP gateway component this may not be supported in which case the output will be sent as per normal.
Property methods: GzipOutputDisplayToLogical(), GzipOutputGet(), GzipOutputIsValid(), GzipOutputLogicalToDisplay(), GzipOutputNormalize()
property HTTPVersion as %String;
Version of HTTP support CSP will report. If this is "" (the default), then use the version reported from the client request. If you need another value such as "HTTP/1.0" even for an HTTP/1.1 request, then set this property to the version on you require.

For an HTTP/2 request, version "HTTP/2.0" is always assumed, and setting this property has no effect.
Property methods: HTTPVersionDisplayToLogical(), HTTPVersionGet(), HTTPVersionIsValid(), HTTPVersionLogicalToDisplay(), HTTPVersionLogicalToOdbc(), HTTPVersionNormalize(), HTTPVersionSet()
property HeaderCharSet as %String;
Sets the Character Set to write out the HTTP headers. If not specified it defaults to UTF-8 which appears to be the standard for most browsers. If you do not want to use any translation you can specify "RAW" for this property.
Property methods: HeaderCharSetDisplayToLogical(), HeaderCharSetGet(), HeaderCharSetIsValid(), HeaderCharSetLogicalToDisplay(), HeaderCharSetLogicalToOdbc(), HeaderCharSetNormalize(), HeaderCharSetSet()
property Headers as %String [ MultiDimensional ];
Maintains the collection of additional HTTP Headers to be sent out. See SetHeader() and GetHeader().
Property methods: HeadersDisplayToLogical(), HeadersGet(), HeadersIsValid(), HeadersLogicalToDisplay(), HeadersLogicalToOdbc(), HeadersNormalize(), HeadersSet()
property InProgress as %Integer [ InitialExpression = 0 ];
Returns true if the request is already in progress -- that is the HTTP headers have been sent, and false otherwise. A read only property.
Property methods: InProgressDisplayToLogical(), InProgressGet(), InProgressIsValid(), InProgressLogicalToDisplay(), InProgressNormalize()
property Language as %String;
The language (RFC 1766 format) in which this page is to be displayed. %response.Language may be set:
1) explicitely by the user,
2) by calling %response.MatchLanguage,
3) by calling %response.GetText with language of "",
4) by calling ##class(%CSP.TagLanguage).GetText or one of the tags implemented using ##class(%CSP.TagLanguage).GetText such as csp:text, div, span.
Property methods: LanguageDisplayToLogical(), LanguageGet(), LanguageIsValid(), LanguageLogicalToDisplay(), LanguageLogicalToOdbc(), LanguageNormalize()
property NoCharSetConvert as %Boolean [ InitialExpression = 0 ];
If the ContentType=text/... or the CharSet is specified then CSP will normally convert to the target charset when writing the page out. However sometimes you may wish to turn this off if for example you do not have this charset installed and just wish to use RAW mode. If so set this property to 1.
Property methods: NoCharSetConvertDisplayToLogical(), NoCharSetConvertGet(), NoCharSetConvertIsValid(), NoCharSetConvertLogicalToDisplay(), NoCharSetConvertNormalize(), NoCharSetConvertSet()
property OutputSessionToken as %Boolean [ InitialExpression = 1 ];
If this property is set to 0 then prevent the session cookie and CSPCHD from being output. Can be useful when serving up static content for example from %CSP.StreamServer. Note that if the value has been set by the CSP server to 0 already you should not set it to 1 as when the CSP server determines a request does not need a session it skips various session related logic and does not define a session cookie value so setting this to 1 will have no effect.
Property methods: OutputSessionTokenDisplayToLogical(), OutputSessionTokenGet(), OutputSessionTokenIsValid(), OutputSessionTokenLogicalToDisplay(), OutputSessionTokenNormalize(), OutputSessionTokenSet()
property Redirect as %String;
Setting this property to a target URL will cause the browser to be redirected to this new page. The result of this is to send a 303 Redirected HTTP header back to the client browser, the browser then requests the new redirected page from the server. This is not as fast as a server side redirect which can be issues using the ServerSideRedirect.

The OnPage() method will not be called if this is set. For example the following CSP page section will redirect to the 'redirect.csp' page. 

<script language="Cache" method="OnPreHTTP" arguments="" returntype="%Boolean">
:	Set %response.Redirect="redirect.csp"
:	Quit 1
</script>
Property methods: RedirectDisplayToLogical(), RedirectGet(), RedirectIsValid(), RedirectLogicalToDisplay(), RedirectLogicalToOdbc(), RedirectNormalize(), RedirectSet()
property ServerSideRedirect as %String;
Setting this property to a URL will make the server redirect to this new page and render this instead of the original URL. This redirection is done entirely on the server which makes it much faster than the Redirect which needs to go all the way back to the browser and then back to the server again. You should set this to a URL without the 'http://machine' part such as '/csp/samples/menu.csp' or it will not be able to parse this correctly and will use a browser redirect instead

Note that as the browser asked for page 'a.csp' and using a server side redirect you display 'b.csp' the browser still thinks it has displayed page 'a.csp' and so will show this URL in the address bar. The OnPage() method will not be called if this is set. For example the following CSP page section will redirect to the 'redirect.csp' page. 

<script language="Cache" method="OnPreHTTP" arguments="" returntype="%Boolean">
:	Set %response.ServerSideRedirect="redirect.csp"
:	Quit 1
</script>
Property methods: ServerSideRedirectDisplayToLogical(), ServerSideRedirectGet(), ServerSideRedirectIsValid(), ServerSideRedirectLogicalToDisplay(), ServerSideRedirectLogicalToOdbc(), ServerSideRedirectNormalize(), ServerSideRedirectSet()
property Status as %String [ InitialExpression = "200 OK" ];
The HTTP Status code to be sent back in the response. The HTTP status codes are defined in RFC 2068.

http://www.faqs.org/rfcs/rfc2068.htmlOpens in a new tab
Property methods: StatusDisplayToLogical(), StatusGet(), StatusIsValid(), StatusLogicalToDisplay(), StatusLogicalToOdbc(), StatusNormalize(), StatusSet()
property Timeout as %Integer;
Can be set in the OnPreHTTP() method of a page in which case this changes the amount of time the CSP gateway will wait for a response from the server in seconds before it reports the 'Server is not responding' error message. This is useful if you know that this page is doing an expensive SQL query that will take a couple of minutes and you want to set the server response timeout on the CSP gateway to a minute and yet wait three minutes for this page to respond. It will just change the server response timeout for this page only. If not set the the CSP gateway uses its default timeout value specified in the CSP gateway configuration.
Property methods: TimeoutDisplayToLogical(), TimeoutGet(), TimeoutIsValid(), TimeoutLogicalToDisplay(), TimeoutNormalize()
property Timers as %Float [ MultiDimensional ];
Used to keep track of how long various pieces of the CSP pages take to render.
Property methods: TimersDisplayToLogical(), TimersGet(), TimersIsValid(), TimersLogicalToDisplay(), TimersNormalize(), TimersSet()
property TraceDump as %Boolean [ InitialExpression = 0 ];
Setting this to true will cause a CSP object dump after the page has been written. This can be very useful for debugging pages.
Property methods: TraceDumpDisplayToLogical(), TraceDumpGet(), TraceDumpIsValid(), TraceDumpLogicalToDisplay(), TraceDumpNormalize(), TraceDumpSet()
property UseASPredirect as %Boolean [ InitialExpression = 0 ];
If true and the CSP web gatway is running on Microsoft Internet Information Server then this will post the output from CSP through the ASP engine on the web server which will output the final HTML. This is done by writing a temporary file on the web server and then asking the ASP engine to render this temporary file. Note you must set this property in the OnPreHTTP() method, i.e. before any message headers have been written out for it to be effective. If you attempt to set this after the header have been written it will generate an error.
Property methods: UseASPredirectDisplayToLogical(), UseASPredirectGet(), UseASPredirectIsValid(), UseASPredirectLogicalToDisplay(), UseASPredirectNormalize()
property UseExactRedirect as %Boolean [ InitialExpression = 0 ];
Typically when performing a browser-side redirect using Redirect the target URL will be transformed to an absolute URL before being sent to the client. The system may also add CSPToken and/or CSPCHD URL parameters as appropriate. If UseExactRedirect is 1, then the server will not perform these transformations; the URL specified in Redirect will be used exactly. This only affects the current request, and does not affect redirects using ServerSideRedirect. The default is 0.
Property methods: UseExactRedirectDisplayToLogical(), UseExactRedirectGet(), UseExactRedirectIsValid(), UseExactRedirectLogicalToDisplay(), UseExactRedirectNormalize(), UseExactRedirectSet()
property UseHttpOnly as %Boolean [ InitialExpression = 1 ];
Use 'HttpOnly' with Session Cookie
Property methods: UseHttpOnlyDisplayToLogical(), UseHttpOnlyGet(), UseHttpOnlyIsValid(), UseHttpOnlyLogicalToDisplay(), UseHttpOnlyNormalize(), UseHttpOnlySet()
property VaryByParam as %String;
This property controls the CSP Gateway output caching mechanism along with the Expires. Output caching is a mechanism to cache the result of a CSP page on the web server and if another client requests the same page it can be given this cached result directly from the web server without making InterSystems IRIS do any work. This can result in significant scalability improvements if this is used carefully. A typical use of this feature may be to cache the inital page on a web portal which displays some news items, some weather information, etc. as everyone coming into the site sees this page first it gets a lot of hits, but it is reasonable to only ask InterSystems IRIS to recreate the page every five minutes which will save a significant amount of work on the server.

The amount of time that the page will sit in the cache on the web server is determined by the Expires (which also determines how long this page sits in the web browsers cache as well. The conditions that must be met to serve up this cached page are determined by the VaryByParam property. Possible values are

  • None - This means that any further request for this page in the period set by Expires will return this cached page, even if the query parameters are different.
  • * - Means that a separate cached copy of this page is retained by the web server for every combination of parameters that are requested. So if user A requests page.csp?VAL=1 and then user B request page.csp?VAL=5 they will not get the cached page, however if user C requests page.csp?VAL=1 then they will get the cached page produced in response to user A's request.
  • A,B,C - Means that just consider the parameters A, B, C in determining which cached page to return, so if user A requests page.csp?A=1&D=5 and then user B requests page.csp?D=10&A=1 then they will get the same page generated for user A.
Property methods: VaryByParamDisplayToLogical(), VaryByParamGet(), VaryByParamIsValid(), VaryByParamLogicalToDisplay(), VaryByParamLogicalToOdbc(), VaryByParamNormalize(), VaryByParamSet()

Methods

final method Abort()
Attempt to abort the response written so far. There are three possibilities:
  • We may have encountered the error before attempting to send any of the content.
  • Content may have been generated, but we have not flushed the buffer and so can still abort.
  • Content has already been sent to the browser, we cannot abort.
So we try to abort the output, and set the InProgress() to 0 if it worked.
method DeleteHeader(name As %String)
Remove a header from the response. Note that name is not case sensitive
method Flush() as %Status
Flush the contents of the output buffer to the web server. This can be useful in large pages where it can display the first section of the page quickly, but then takes a few seconds to perform some calculation for the second half of the page. If you flush the output buffer after writing the first half of the page then the browser may (this is not always true, it depends on what you are outputting and how the browser parses the HTML) be able to display the first section of the page. This can make the page look more responsive. This should be used sparingly because buffering the output significantly improves the performance of CSP and the output is automatically flushed at the end of a page.
method GetHeader(name As %String) as %String
Return the value of the name header. Note that name is not case sensitive
method GetText(language As %String = "", domain As %String = "", id As %String, default As %String, args...) as %String
Get and format message text for the page being output. Language is optional and %response.Language is used, if language is "" or not specified. Language will be converted to lower case before being used. Domain can be a system domain beginning with % or a application domain. Domain is optional and %response.Domain is used, if domain is "" or not specified. Id is any message id. Arguments of the form %1, %2, etc will be replaced by macro arguments that follow the default argument. Return a the string specified by the default argument, if message text not found. If the default argument is not specified, then string for the default language or English is used as the default.
deprecated final classmethod HyperEventBody() as %String
This method is deprecated since Java applet based hyperevents are no longer supported.

method MatchLanguage() as %String
Find and return the language (RFC 1766 format) in which this page is to be displayed. The %response Language attribute is used as the default language for csp:text, span and div tags. If %response.Language is not set by the CSP page, then %response.Language is set to %session.Language. In turn, if %session.Language has not set been already set, then it is set to the best fit from the HTTP_ ACCEPT_LANGUAGE CGI variable using #class(%MessageDictionary).MatchLanguage based on the current %response.Domain. The domain for a specific csp:text, div or span tag does not influence the selection of language.
final method Reset(redirect As %Boolean = 0)
Resets this %CSP.Response object to its initial state
method SetCookie(name As %String, value As %String, expires As %String = "", path As %String = "", domain As %String = "", secure As %Boolean = 0, httpOnlyFlag As %Boolean = 0, sameSite As %String = "")
Sets a cookie into the reply. All cookies must be set before the HTTP headers are written so they need to be created in the OnPreHTTP() method. The sameSite attribute defaults to the session's User Cookie Scope setting. If specified, it must be "Strict", "Lax", or "None" (case insensitive). If "None", the Secure flag is required.
method SetHeader(name As %String, value As %String)
Sets a custom HTTP header into the reply. All headers must be set before the HTTP headers are written (after OnPreHTTP() completes). If you set the same header twice it will append the information to the first with a ',' between them. Note that name is not case sensitive, however we will remember the case of the header when sending this to the client.
method SetHeaderIfEmpty(name As %String, value As %String) as %Boolean
Helper method that sets a header if it is currently empty, if it already has a value it does nothing. Returns true if the header was set and false if it did nothing.
final method WriteHTTPHeader(ByRef OutputBody As %Boolean) as %Status
Called by the CSP runtime to render the contents of the %response object as HTTP headers.
method WriteHTTPHeaderCookies()

Inherited Members

Inherited Methods

FeedbackOpens in a new tab