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 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.
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.
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:
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.
This will insert 'Name' twice, first with 'Value' and then with 'Value2'.
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.
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.
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.
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 '1.0' to report 'HTTP/1.0' even for a HTTP/1.1 request
then set this property to the version on you require.
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.
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 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
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.
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.
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.
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 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
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.
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.
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
method DeleteHeader(name As %String) [ Language = objectscript ]
Remove a header from the response. Note that name is not case sensitive
method Flush() as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
Return the value of the name header.
Note that name is not case sensitive
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.
final classmethod HyperEventBody() as %String [ Language = objectscript ]
This method is deprecated since Java applet based hyperevents are no longer supported.
method MatchLanguage() as %String [ Language = objectscript ]
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
final method Reset(redirect As %Boolean = 0) [ Language = objectscript ]
Resets this %CSP.Response object to its initial state
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) [ Language = objectscript ]
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.