Last updated:

Preface

The Context object is the interface to the web application server context. It contains the built in Request, Response, Security, and Session objects that are available when handling a web request. This object supersedes other ways to access web application server context (see Server Programming Changes for Version 11) and was made to so that the same object methods and properties will work on the stand-alone server and IIS. Web applications that were built before the Context object was available or using now deprecated functions or objects should be updated to use the Context object so that the web application will transition to running under IIS or any other web server technology available in the future.

Here are a few examples of using the Context object compare with the functions you would use before the Context object was available.

Pre-Context objectContext object
a5ws_GetCurrentUser()Context.Security.CurrentUser
Application.Path()Context.Request.ApplicationRoot
a5ws_securityactive()Context.Security.IsActive

Context

Type: A5AS::A5INETServerIntegration::IA5ServerContext

The Context object is automatically available to Xbasic code that runs on the stand-alone application server and the IIS application server. It has all properties needed to handle an HTTP request and response. Using the Context object is the preferred way to get information about a request, response, or other context of the server since other objects have been deprecated since version 11. Many of the deprecated objects will not work under IIS.

Properties

GridCache r/o

Type: Alpha5DotNet.DataCache

HostContext r/o

Type: P

The type of HostContext depends on the platform that the code is running under. Under IIS HostContext is of type System.Web.HttpContext and all properties and methods available on that .NET object are available in Xbasic. Under the stand-alone application server HostContext is of type A5AS::A5INETServerIntegration::A5WServerContext.

HostContextName r/o

Type: C

Context.HostContextName contains the name of the platform on which the code is running. This will be "IIS" when running on IIS and will be "Alpha Five Web Server" when running on the stand-alone server.

Request r/o

Type: A5AS::A5INETServerIntegration::IA5Request

Context.Request contains methods and properties for the current HTTP request.

Response r/o

Type: A5AS::A5INETServerIntegration::IA5Response

Context.Response contains methods and properties for the current HTTP response.

Security r/o

Type: A5AS::A5INETServerIntegration::IA5WebSecurityContext

Context.Security contains the methods and properties available for working with security.

Session r/o

Type: A5AS::A5INETServerIntegration::IA5WebSessionContext

Context.Session contains the methods and properties available for working with the current session.

Methods

Context has no methods.

Request

The Request object contains properties and methods available for working with the current HTTP request.

Properties

ApplicationRoot r/o

Type: C

Context.Request.ApplicationRoot is the absolute physical path to the application on the server.

ApplicationRootUrl r/o

Type: C

Context.Request.ApplicationRootUrl is the root url to the application. This is guaranteed to end with a forward slash ("/").

A5wIncludePath r/o

Type: C

Context.Request.A5wIncludePath is the absolute physical path to the location of the application's a5w files.

ContentLength r/o

Type: N

Context.Request.ContentLength is the length of the current request's content.

ContentType r/w

Type: C

Context.Request.ContentType is the MIME type of the current request's content such as text/html or application/json.

Cookies r/o

Type: System::Web::HttpCookieCollection

Context.Request.Cookies is the collection of the current request's cookies.

Form r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Request.Form is the collection of the current request's form variables. The collection will have 0 entries if the page making the request does not have any forms on it.

Headers r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Request.Headers is the collection of the current request's HTTP headers.

Host r/o

Type: C

Context.Request.Host is the value of the HTTP Host header.

HttpMethod r/o

Type: C

Context.Request.HttpMethod is the current request's HTTP method such as GET, POST, or HEAD.

IsLocal r/o

Type: L

Context.Request.IsLocal indicates whether the current request was made on the same machine as the server. For instance, the request made by a browser was "http://localhost/index.a5w". This can be useful to add what may be sensitive diagnostic/debug information to a response knowing that it will only be added when the request was made on the same machine as the server.

IsWorkingPreview r/o

Type: L

Context.Request.IsWorkingPreview will be .T. if the request is being processed in working preview. Otherwise, it is .F.

Params r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Request.Params is a single collection that includes all the items in the following collections in this order: QueryString, Form, Cookies, and ServerVariables.

QueryString r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Request.QueryString is a collection of the current request's query string's parsed name/value pairs. To get an unparsed query string use the ToString() method: Context.Request.QueryString.ToString().

To get the "firstName" query string value from this request, "http://www.acme.com/search/?firstName=John&lastName=Doe" use the following Xbasic:

Context.Request.QueryString.Get("firstName")

RawUrl r/o

Type: C

Context.Request.RawUrl is the current request's URL with the protocol and domain prefix removed. The RawUrl for a request made with this URL "http://www.acme.com/search/?firstName=John&lastName=Doe" would be "/search/?firstName=John&lastName=Doe"

Referer r/o

Type: C

Context.Request.Referer is the value of the HTTP Referer header.

Remote_Addr r/o

Type: C

Context.Request.Remote_Addr is an alias of UserHostAddress and is provided for compatibility with Alpha Anywhere web applications that were written to run on the stand-alone server.

Request_Uri r/o

Type: C

Context.Request.Request_Uri is an alias of RawUrl and is provided for compatibility with Alpha Anywhere web applications that were written to run on the stand-alone server.

ScriptName r/o

Type: C

Context.Request.ScriptName is an alias for the current request's PATH_INFO server variable.

Script_Name r/o

Type: C

Context.Request.Script_Name is an alias for ScriptName.

ServerVariables r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Request.ServerVariables is a collection of the web server variables. The follow is a list of variables that are supported on both IIS and the stand-alone application server. When running under IIS there may be other server variables available. See the Microsoft documentation for more details.

The following code is an example of how to retrieve a server variable:

Context.Request.ServerVariables.Get("HTTP_REFERER")

TemporaryDirectory r/o

Type: C

Context.Request.TemporaryDirectory is the path to a temporary directory that is a unique for the request and is valid for the duration of a request. When the request is finished the directory is deleted. The directory path will always end with a back-slash ("\").

UserAgent r/o

Type: C

Context.Request.UserAgent is the UserAgent string that is sent by the browser.

UserHostAddress r/o

Type: C

Context.Request.UserHostAddress is the IP host address of the remote client.

Variables r/o

Type: P

Context.Request.Variables

Methods

GetRequestTempFileName

GetRequestTempFileName as C (FileExtension as C = ".tmp")

Return type: C
The name of a temporary file.

Arguments

FileExtension as C This is optional and defaults ".tmp".

Context.Request.GetRequestTempFileName() creates temporary file with the specified extension. The file is valid for the duration of the request. When the request is finished the file is deleted.

Response

Properties

Cache r/o

Type: System::Web::HttpCachePolicy

Context.Response.Cache is used to control the cache HTTP headers. See the Microsoft documentation for HttpCachePolicy for more details.

ContentEncoding r/w

Type: System::Text::Encoding

Context.Response.ContentEncoding is used to get or set the content encoding of the response.

ContentType r/w

Type: C

Context.Response.ContentType is used to get or set the MIME type of the response content. It defaults to "text/html".

Cookies r/o

Type: System::Web::HttpCookieCollection

Context.Response.Cookies is the collection of the current response's cookies.

Headers r/o

Type: System::Collections::Specialized::NameValueCollection

Context.Response.Headers is the collection of the current response's HTTP headers.

OutputStream r/o

Type: System::IO::Stream

Context.Response.OutputStream is the raw contents of the HTTP response content.

RedirectLocation r/w

Type: C

Context.Response.RedirectLocation is used to get or set the absolute URI that will be sent in the Location header of the response.

StatusCode r/w

Type: N

Context.Response.StatusCode is used to get or set HTTP status code of the response.

StatusDescription r/w

Type: C

Context.Response.StatusDescription is used to get or set the description for the StatusCode of the response.

Methods

AppendCookie

AppendCookie as V (Cookie as System::Web::HttpCookie)

Return type: V

Arguments

Cookie as System::Web::HttpCookie The cookie to add.

Context.Response.AppendCookie(Cookie) adds a cookie to the response's cookie collection.

Note: This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.

AppendHeader

AppendHeader as V (Name as C, Value as C)

Return type: V

Arguments

Name as C The name of the HTTP header item.
Value as C The value of the HTTP header item.

Context.Response.AppendHeader(Name, Value) adds an HTTP header to the current response.

BinaryWrite

BinaryWrite as V (BodyBlob as B)

Return type: V

Arguments

BodyBlob as B.

Context.Response.BinaryWrite() Write bytes to the response's output stream.

Clear

Clear as V ()

Return type: V

Arguments

None

Context.Response.Clear() removes all content from the OutputStream of the current response. Response header output is not affected.

ClearContent

ClearContent as V ()

Return type: V

Arguments

None

Context.Response.ClearContent() is an alias for Clear.

ClearHeaders

ClearHeaders as V ()

Return type: V

Arguments

None

Context.Response.ClearHeaders() removes all HTTP headers from the current response.

End

End as V ()

Return type: V

Arguments

None

Context.Response.End() causes the current response to immediately complete with no further processing.

NoCache

NoCache as V ()

Return type: V

Arguments

None

Context.Response.NoCache() configures the current response so that the browser receiving the response will not cache it. It does this by setting the following three HTTP headers:

Header NameHeader Value
Cache-Control"no-store, no-cache, max-age=0, must-revalidate" (for HTTP/1.1)
Expires"Mon, 09 Jun 2003 09:25:00 GMT" (for HTTP/1.0)
Pragma"no-cache"

Redirect

Redirect as V (Url as C, EndResponse as L = .T.)

Return type: V

Arguments

Url as C The URL to which the client should be redirected.
EndResponse as L Optional. Flag for whether page execution should terminate immediately or not. This defaults to .T.

Context.Response.Redirect() Redirect the client by returning a 302 Redirect HTTP status code and optionally terminate processing the current page.

RedirectPermanent

RedirectPermanent as V (Url as C, EndResponse as L = .T.)

Return type: V

Arguments

Url as C The URL to which the client should be redirected.
EndResponse as L Optional. Flag for whether page execution should terminate immediately or not. This defaults to .T.

Context.Response.RedirectPermanent() Redirect the client by returning a 301 Redirect permanent HTTP status code and optionally terminate processing the current page.

SendFile

SendFile as V (Filename as C, PromptToSave as L = .F., OutputFilename as C = "__not__specified__")

Return type: V

Arguments

Filename as C The name of the file to written to the response's output.
PromptToSave as L Optional. Add the Content-Disposition header to the client will prompt for save. This defaults to .F. when an OutputFilename is not specified. It defaults to .T. when an OutputFilename is specified.
OutputFilename as C Optional. The name the client should use when saving the file.

Context.Response.SaveFile() Write the content of a file directly to the response's output stream.

Write

Write as V (BodyData as C)
Write as V (BodyData as B)
Write as V (BodyData as N)
Write as V (BodyData as L)

Return type: V

Arguments

BodyData as C
BodyData as B
BodyData as N
BodyData as L

Context.Response.Write() Write a character, binary, number or logical to the response's output stream. Character and Binary types are written directly to the response's output stream. Number and logical type values are converted to character before being written to the output stream.

Security

The Security object contains properties and methods available for working with the users and roles if a web application uses security. The term "Role" and "Group" are synonymous in this API. The UI in Alpha Anywhere Developer Edition generally uses the term "Group" while the security property and methods use the term "Roles".

Note: The Security object has a CallResult property. Use this property to see if a method call or property get succeeds before using a method's returned value or property's value. See the following examples:

dim errorMsg as C = "" dim created as L = .F. created = Context.Security.CreateUser("John-Doe@acme.com", "secret") if Context.Security.CallResult.Success then if .not. created then error_generate("User was not created.") end if else error_generate(Context.Security.CallResult.Text) end if

dim userName as C = Context.Security.CurrentUser if .not. Context.Security.CallResult.Success then error_generate(Context.Security.CallResult.Text) end if if alltrim(userName) = "" then 'Display "no user is logged in." else 'Display user name end if

Properties

CallResult r/o

Type: CallResult

Context.Security.CallResult is used to check the success or failure of a method call or property get in the Security object. See the note in the Security class description above for more details and examples.

CurrentUser r/o

Type: C

Context.Security.CurrentUser returns the name of the current user if one is logged in. Otherwise a zero length character value is returned. Check Context.Security.CallResult.Success, before using the value that is returned.

DefaultRoles r/o

Type: C

Context.Security.DefaultRoles returns a crlf delimited list of the default roles to which a new user will be assigned. This value is set in the security settings on the Customize Options tab. Check Context.Security.CallResult.Success, before using the value that is returned.

IsActive r/o

Type: L

Context.Security.IsActive returns .T. if the web application is running with security and returns .F. if the web application is not running with security. Check Context.Security.CallResult.Success before using the value that is returned.

PasswordChangeOnFirstUse r/o

Type: L

Context.Security.PasswordChangeOnFirstUse returns .T. if users are required to change password on first use. Check Context.Security.CallResult.Success before using the value that is returned.

PasswordExpirationTime r/o

Type: N

Context.Security.PasswordExpirationTime returns the number of minutes user's password expires after it was last changed. A value of 0 means passwords don't expire. The default is set to 1 year (525,600 minutes) in the security configuration in the Developer Edition. Check Context.Security.CallResult.Success before using the value that is returned.

PasswordExpires r/o

Type: L

Context.Security.PasswordExpires returns .T. if passwords for users can expire. Check Context.Security.CallResult.Success before using the value that is returned.

PasswordResetAllowed r/o

Type: L

Context.Security.PasswordResetAllowed returns .T. if users are allowed to reset their password. Check Context.Security.CallResult.Success before using the value that is returned.

PasswordRetrievalAllowed r/o

Type: L

Context.Security.PasswordRetrievalAllowed returns .T. if users are allowed to retrieve their password. Check Context.Security.CallResult.Success before using the value that is returned.

RequiresQuestionAndAnswer r/o

Type: L

Context.Security.RequiresQuestionAndAnswer returns .T. if users are required to supply an answer to a security question in order to reset or retrieve their password. Check Context.Security.CallResult.Success before using the value that is returned.

RolesAreEnabled r/o

Type: L

Context.Security.RolesAreEnabled returns a .T. if roles are enabled for the security settings of the application. .F. is returned otherwise. Check Context.Security.CallResult.Success, before using the value that is returned.

SecurityQuestionList r/o

Type: C

Context.Security.SecurityQuestionList returns a crlf delimited string of security questions defined by the security system. Use this list when a user is created or updated and a security question needs to be selected. Check Context.Security.CallResult.Success, before using the value that is returned.

Methods

AddUserToRole

AddUserToRole as L (UserName as C, RoleName as C)

Return type: L
.T. if the role was added; otherwise .F.

Arguments

UserName as C The name of the user.
RoleName as C The name of the role to which the user will be added.

Context.Security.AddUserToRole() adds a user to the supplied role. Check Context.Security.CallResult.Success before using the return value.

AddUserToRoles

AddUserToRoles as L (UserName as C, RoleNames as C)

Return type: L
.T. if roles were added; otherwise .F.

Arguments

UserName as C The name of the user.
RoleNames as C The names of the roles to which the user will be added. Role names are separated by crlf.

Context.Security.AddUserToRoles() adds a user to the supplied roles. Check Context.Security.CallResult.Success before using the return value.

AdministrativeResetPassword

AdministrativeResetPassword as C (UserName as C)

Return type: C
The newly generated password.

Arguments

UserName as C The name of the user.

Context.Security.AdministrativeResetPassword() reset the user's password to a generated password. This method can be used whether or not a password answer is required so its use should be limited to pages/code that require administrative access. The return value is the newly generated password. Check Context.Security.CallResult.Success before using the return value.

ChangeEmail

ChangeEmail as L (UserName as C, Email as C)

Return type: L
.T. if the user's email address was changed; otherwise .F.

Arguments

UserName as C The name of the user.
Email as C The user's email address.

Context.Security.ChangeEmail() changes the email address for the user. Check Context.Security.CallResult.Success before using the return value.

ChangePassword

ChangePassword as L (UserName as C, OldPassword as C, NewPassword as C)

Return type: L
.T. if the user's password was changed; otherwise .F.

Arguments

UserName as C The name of the user as is used during login.
OldPassword as C The user's current password.
NewPassword as C The user's new password.

Context.Security.ChangePassword() changes the password for the user. Check Context.Security.CallResult.Success before using the return value.

ChangePasswordQuestionAndAnswer

ChangePasswordQuestionAndAnswer as L (UserName as C, Password as C, Question as C, Answer as C)

Return type: L
.T. if the user's question and answer were changed; otherwise .F.

Arguments

UserName as C The name of the user as is used during login.
Password as C The user's password.
Question as C The user's new security question.
Answer as C The user's new security answer.

Context.Security.ChangePasswordQuestionAndAnswer() changes the security question and security answer for the user. Check Context.Security.CallResult.Success before using the return value.

CreateUser

CreateUser as L (UserName as C, Password as C, IsApproved as L = .T.)
CreateUser as L (UserName as C, Password as C, Email as C, IsApproved as L = .T.)
CreateUser as L (UserName as C, Password as C, Email as C, PasswordQuestion as C, PasswordAnswer as C, IsApproved as L = .T.)

Return type: L
.T. if the user is created; otherwise .F.

Arguments

UserName as C The name of the new user.
Password as C The password for the new user.
Email as C The email address of the new user.
PasswordQuestion as C The question to be used for password reset.
PasswordAnswer as C The answer to the PasswordQuestion to be used for password reset.
IsApproved as L Set the user to being approved for login or not approved for login. If this value is set to .F. the user will not be able to login even if the credentials are valid. Optional. Defaults to .T.

Context.Security.CreateUser() adds a new user with a password. There are method overloads for creating a user with an email address and a password question and answer. Check Context.Security.CallResult.Success before using the return value.

CreateRole

CreateRole as L (RoleName as C)

Return type: L
.T. if role is created; otherwise .F.

Arguments

RoleName as C The name of the role to be created.

Context.Security.CreateRole() adds a role. Check Context.Security.CallResult.Success before using the return value.

DeleteUser

DeleteUser as L (UserId as C)

Return type: L
.T. if the user is deleted; otherwise .F.

Arguments

UserId as C The name of the user to be deleted.

Context.Security.DeleteUser() delete the specified user. Check Context.Security.CallResult.Success before using the return value.

DeleteRole

DeleteRole as L (RoleName as C)

Return type: L
.T. if role is deleted; otherwise .F.

Arguments

RoleName as C The name of the role to be deleted.

Context.Security.DeleteRole() removes a role. A role must not have any users associated with it in order for it to be deleted. Check Context.Security.CallResult.Success before using the return value.

GetEmail

GetEmail as C ()
GetEmail as C (UserName as C)

Return type: C
The email address for a user, if any.

Arguments

UserName as C Optional. The user name for which the email address is to be retrieved. If no user name is used then the email address for the current user will be retrieved.

Context.Security.GetEmail() gets the email address of the specified user, or when no user is specified, gets the email address of the current user. Check Context.Security.CallResult.Success before using the return value.

GetLastPasswordChangedDate

GetLastPasswordChangedDate as T ()
GetLastPasswordChangedDate as T (UserName as C)

Return type: T
The date that the user's password was last changed.

Arguments

UserName as C Optional. The user name for which the password last changed date is to be retrieved. If no user name is used then the password last changed date for the current user will be retrieved.

Context.Security.GetLastPasswordChangedDate() gets the password last changed date of the specified user, or when no user is specified, gets the password last changed date of the current user. Check Context.Security.CallResult.Success before using the return value.

GetPasswordQuestion

GetPasswordQuestion as C ()
GetPasswordQuestion as C (UserName as C)

Return type: C
The password question, if any.

Arguments

UserName as C Optional. The user name for which the password question is to be retrieved. If no user name is used then the password question for the current user will be retrieved.

Context.Security.GetPasswordQuestion() gets the password question of the specified user, or when no user is specified, gets the password question of the current user. Check Context.Security.CallResult.Success before using the return value.

GetRoles

GetRoles as C ()

Return type: C
a crlf delimited list of roles.

Arguments

None.

Context.Security.GetRoles() gets a list of all the roles defined in the application's security settings. Check Context.Security.CallResult.Success before using the return value.

GetRoleUsers

GetRoleUsers as C (RoleName as C)

Return type: C
a crlf delimited list of users.

Arguments

RoleName as C The name of the role.

Context.Security.GetRoleUsers() gets a list of the users which are members of a role. Check Context.Security.CallResult.Success before using the return value.

GetUserRoles

GetUserRoles as C (UserName as C = null_value())

Return type: C
a crlf delimited list of roles.

Arguments

UserName as C The name of the user.

Context.Security.GetUserRoles() gets a list of the roles to which the user belongs. Check Context.Security.CallResult.Success before using the return value.

GetUser

GetUser as C (ProviderKey as A)

Return type: C
The user name or empty string if no user name is found for the given ProviderKey

Arguments

ProviderKey as A The ProviderKey must be a value and type as returned from a call to Context.Security.GetUserProviderKey().

Context.Security.GetUser() gets the user name for a given ProviderKey. Check Context.Security.CallResult.Success before using the return value.

GetUserProviderKey

GetUserProviderKey as A ()
GetUserProviderKey as A (UserName as C)

Return type: A

UserName as C Optional. Retrieve the provider key for a user. If no user name is specified then the current user will be used.

Context.Security.GetuserProviderKey() gets the provider defined key for a user. Check Context.Security.CallResult.Success before using the return value. The provider key for a user is defined by the underlying security store. It can be used with Context.Security.GetUser to get the user's name. When used with Context.Security.GetUser the value must be of the same type as returned from this method.

GetUsers

GetUsers as C ()

Return type: C
A crlf delimited string of all the users in the system.

Arguments

None

Context.Security.GetUsers() gets a list of all the users. Check Context.Security.CallResult.Success before using the return value.

IsCurrentUserInRole

IsCurrentUserInRole as L (RoleName as C)

Return type: L
.T. if the current user is in the role; otherwise .F.

Arguments

RoleName as C The name of the role.

Context.Security.IsCurrentUserInRole() checks to see if the current user is in a role. Check Context.Security.CallResult.Success before using the return value.

IsCurrentUserInRoles

IsCurrentUserInRoles as L (RoleNames as C)

Return type: L
.T. if the current user is in at least one of the specified roles; otherwise .F.

Arguments

RoleNames as C The name of the roles. The role names are separated by a comma or a space ("," or " ").

Context.Security.IsCurrentUserInRole() checks to see if the current user is in at least one of supplied roles. Check Context.Security.CallResult.Success before using the return value.

IsUserInRole

IsUserInRole as L (UserName as C, RoleName as C)

Return type: L
.T. if user is in the role; otherwise .F.

Arguments

UserName as C The name the user.
RoleName as C The name of the role.

Context.Security.IsUserInRole() checks to see if the user is in a role. Check Context.Security.CallResult.Success before using the return value.

IsUserInRoles

IsUserInRoles as L (UserName as C, RoleNames as C)

Return type: L
.T. if the user is in at least one of the specified roles; otherwise .F.

Arguments

UserName as C The name the user.
RoleNames as C The name of the roles. The role names are separated by a crlf.

Context.Security.IsUserInRoles() checks to see if the user is in at least one of supplied roles. Check Context.Security.CallResult.Success before using the return value.

LockOutUser

LockOutUser as L ()
LockOutUser as L (UserName as C)

Return type: L
.T. if the user was locked out; otherwise .F.

Arguments

UserName as C Optional. The user name of the user to be locked out. If no user name is used then the current user is locked out.

Context.Security.LockOutUser() locks out the specified user, or when no user is specified, the current user is locked out. Check Context.Security.CallResult.Success before using the return value.

Login

Login as L (UserName as C, Password as C, RedirectPage as C = null_value(), ClientCookie as L = .F., DaysUntilExpiration as N = 10)

Return type: L
.T. if the user is logged in; otherwise .F.

Arguments

UserName as C The name of the user.
Password as C The password for the user.
RedirectPage as C The page the user will be redirected to on successful login. If not specified the application defined redirect page will be used.
ClientCookie as L Set to .T. to create a persistent cookie. This type of cookie will remain across browser sessions. That is, if you close your browser and restart the cookie will be available. When set to .F. the cookie will not be available across browser sessions. The cookie is deleted when close your browser. This is the default and is a more secure setting.
DaysUntilExpiration as N The number of days the authentication cookie is valid. This is calculated from the time of the last request made with the cookie.

Context.Security.Login() logs in a user and optionally letting you redirect the successful login to a specific page and set the authentication cookie's lifetime. When login is successful the Context.Security.CallResult.ReturnDataValue will contain the redirect page URL. Check Context.Security.CallResult.Success before using the return value.

Logout

Logout as L ()

Return type: L
.T. if the user is logged out; otherwise .F.

Arguments

None.

Context.Security.Logout() logs out the current user. Check Context.Security.CallResult.Success before using the return value.

PasswordHasExpired

PasswordHasExpired as L ()
PasswordHasExpired as L (UserName as C)

Return type: L
.T. if the user was removed from the role; otherwise .F.

UserName as C Optional. The user name to check for password expiration. If no user name is used then the password expiration check is done for the current user.

Context.Security.PasswordHasExpired() gets whether or not the password of the specified user has expired. The maximum lifetime of a password is defined in the security settings. Check Context.Security.CallResult.Success before using the return value.

RemoveUserFromRole

RemoveUserFromRole as L (UserName as C, RoleName as C)

Return type: L
.T. if the user was removed from the role; otherwise .F.

Arguments

UserName as C The name of the user to be removed from the role.
RoleName as C The name of the role from which the user should be removed.

Context.Security.RemoveUserFromRole() removes a user from a role. Check Context.Security.CallResult.Success before using the return value.

RemoveUserFromRoles

RemoveUserFromRoles as L (UserName as C, RoleNames as C)

Return type: L
.T. if the user was removed from the roles; otherwise .F.

Arguments

UserName as C The name of the user to be removed from the role.
RoleNames as C A list of role names from which the user should be removed. Role names are separated by a crlf.

Context.Security.RemoveUserFromRoles() removes a user from one or more roles. Check Context.Security.CallResult.Success before using the return value.

ResetPassword

ResetPassword as C (UserName as C, PasswordAnswer as C = null_value())

Return type: C
The newly generated password.

Arguments

UserName as C The name of the user.
PasswordAnswer as C The value must match the password answer set for the user when the selected membership provider requires a password answer for password reset. The match is case-insensitive for SqlServerMembership provider. This is the provider used when the publish profile uses "SqlServer" for the Membership provider.

Context.Security.ResetPassword() reset the user's password to a generated password. If a password answer is required PasswordAnswer must be supplied. The return value is the newly generated password. Check Context.Security.CallResult.Success before using the return value.

RoleExists

RoleExists as L (RoleName as C)

Return type: L
.T. if the role exists; otherwise .F.

Arguments

RoleName as C The name of the role.

Context.Security.RoleExists() checks if a role exists. Check Context.Security.CallResult.Success before using the return value.

SetExpirePasswordImmediate

SetExpirePasswordImmediate as V (UserName as C, Expire as L)

Return type: V

Arguments

UserName as C The name of a user.

Expire as L Use .T. to set the user's password as expired. Use .F. to set the user's password as no longer expired. (See note below.)

Context.Security.SetExpirePasswordImmediate() sets or clears a user's password as expired or not. Check Context.Security.CallResult.Success to check whether the method was successful or not. After this method is called with Expire set to .T. a call to PasswordHasExpired() with the same user name will return .T. whether or not the password expiration timespan has elapsed or not.

Note: Context.Security.SetExpirePasswordImmediate() does not affect the last changed timestamp of the user's password. Calling this method with Expire .T. and then calling it again with .F. will not reset the password's last changed timestamp. Only an actual password change will update the password's last changed timestamp.

TestPassword

TestPassword as L (Password as C)

Return type: L
.T. if the password is valid based on validation settings; otherwise .F.

Arguments

Password as C A password.

Context.Security.TestPassword() Checks the validity of a password against the validation configuration in the security settings. Check Context.Security.CallResult.Success before using the return value.

TestUsername

TestUsername as L (UserName as C)

Return type: L
.T. if the user name is valid based on user name validation settings; otherwise .F.

Arguments

UserName as C A user name.

Context.Security.TestUsername() Checks the validity of a user name against the validation configuration in the security settings. Check Context.Security.CallResult.Success before using the return value.

UnlockUser

UnlockUser as L (UserName as C)

Return type: L
.T. if the user is unlocked; otherwise .F.

Arguments

UserName as C The name of the user.

Context.Security.UnlockUser() will allow a user to login to the application. Check Context.Security.CallResult.Success before using the return value.

UserExists

UserExists as L (UserName as C)

Return type: L
.T. if the user exists; otherwise .F.

Arguments

UserName as C The name of the user.

Context.Security.UserExists() checks if the user exists. Check Context.Security.CallResult.Success before using the return value.

UserIsLockedOut

UserIsLockedOut as L (UserName as C)

Return type: L
.T. if the user is locked out; otherwise .F.

Arguments

UserName as C The name of the user.

Context.Security.UserIsLockedOut() checks if the user is locked out from logging into the application. Check Context.Security.CallResult.Success before using the return value.

ValidateUser

ValidateUser as L (UserName as C, Password as C)

Return type: L
.T. if the credentials are valid; otherwise .F.

Arguments

UserName as C The name of the user.
Password as C The user's password.

Context.Security.ValidateUser() validates the supplied credentials. Check Context.Security.CallResult.Success before using the return value.

Session

The Session object contains properties and methods available for working with a server session. On the stand-alone application server session data is stored in memory in the same process as the application server. On IIS session data can be stored in one of many different ways. Session data can be stored in process like the stand-alone application server, in a state server which is another process on the same machine as the web server, or in a database (SQL or NoSql) depending on the session state provider that is selected for the application. Methods on the session object may have different performance characteristics depending on the session storage that is used.

Note: The Session object has a CallResult property. Use this property to see if a method call or property get succeeds before using a method's returned value or property's value. See the following examples:

dim errorMsg as C = "" Context.Session.Add("lastVisitedPage", "secret") if .not. Context.Session.CallResult.Success then 'Note: This error is most likely caught and handled and does not cause a page error. error_generate(Context.Session.CallResult.Text) end if

Properties

CallResult r/o

Type: CallResult

Context.Session.CallResult is used to check the success or failure of a method call or property get or set in the Session object. See the note in the Session class description above for more details and example.

CookieMode r/o

Type: System::Web::HttpCookieMode

Context.Session.CookieMode indicates whether the application is configured for cookieless sessions.

Count r/o

Type: N

Context.Session.Count is the number of items in the session-state collection.

IsCookieless r/o

Type: L

Context.Session.IsCookieless indicates where the session id is returned to the client. If .T. the session id is added to the URL. Otherwise, the session id is stored in a cookie.

IsNewSession r/o

Type: L

Context.Session.IsNewSession if .T. indicates the session was create during the current request. Otherwise, the session was created by some prior request.

IsReadOnly r/o

Type: L

Context.Session.IsReadOnly if .T. indicates the session is read-only. Otherwise, the session is read-write.

IsSynchronized r/o

Type: L

Context.Session.IsSynchronized if .T. indicates that access to the session-state variables is thread safe. Otherwise, manual synchronization of session-state variable access needs to be done.

Keys r/o

Type: System::Collections::Specialized::NameObjectCollectionBase::KeysCollection

Context.Session.Keys is a collection of all the keys in the session-state.

Mode r/o

Type: System::Web::SessionState::SessionStateMode

Context.Session.Mode specifies how the session-state is stored.

SessionId r/o

Type: C

Context.Session.SessionId is the unique identifier for the session.

Timeout r/w

Type: N

Context.Session.Timeout gets or sets the time, in minutes, for a session to be terminated due to inactivity.

Timestamp r/o

Type: T

Context.Session.Timestamp is the timestamp for when the session was created. The value is local time on the server.

UniqueDataKey r/o

Type: C

Context.Session.UniqueDataKey generated a unique value each time it is accessed. The value is the 32 digits of a Guid prepended with "DTA" resulting in a value that looks like this: DTA114ea94b16924e30ace6bef15c75d8f4.

Variables r/o

Type: P

Context.Session.Variables is the way to access session-state collection values directly. Using Context.Session.Variables.MySessionVar = "MySessionVarValue" is equivalent to using Context.Session.Add("MySessionVar", "MySessionVarValue"). Note that Context.Session.MySessionVar is also equivalent to Context.Session.Variables.MySessionVar, but that Context.Session.Variables.MySessionVar is preferred. See an example .a5w page below.

Note: The Server Programming Changes for Version 11 states that session variables can only be strings and that other variables types are not supported and may not work as expected. This also means that dots (".") are not allowed in the session variable name. That is, Context.Session.Variables.MySessionVar.FirstName is not allowed.

Example .a5w page using session variables.

<html> <head> </head> <body> <pre> <%a5 Context.Session.Variables.ASessionVar = "Value for ASessionVar." Context.Session.Add("AnotherSessionVar", "Value for AnotherSessionVar.") ?*html_escape(property_to_string(Context.Session.Variables)) + crlf() Context.Session.SaveData("ASessionVar", "Changed value for ASessionVar.") ?*html_escape(property_to_string(Context.Session.Variables)) + crlf() %> </pre> </body> </html>

Methods

Abandon

Abandon as V ()

Return type: V

Arguments

None.

Context.Session.Abandon() terminates the current session. Check Context.Session.CallResult.Success before using the return value.

Add

Add as V (Name as C, Value as A)

Return type: V

Arguments

Name as C The name of the session-state variable.
Value as A The value of the session-state variable. Although type A, any type, is allowed it is deprecated for the value. The value should be of type C in order to support the most types of session-state providers under IIS.

Context.Session.Add() adds a named value to the session-state collection. Check Context.Session.CallResult.Success before using the return value.

Clear

Clear as V ()

Return type: V

Arguments

None.

Context.Session.Clear() empties the entire session-state collection. Check Context.Session.CallResult.Success before using the return value.

DeleteSessionFile

DeleteSessionFile as L (Key as C)

Return type: L

Arguments

Key as C The key of the data in the session-state collection. The value of key is a file name without any path components.

Context.Session.DeleteSessionFile() deletes the value session-state key from the session-state collection under IIS. Under the stand-alone application server, the session file in the stand-alone application server's session folder is deleted. Check Context.Session.CallResult.Success before using the return value.

FormatFileDataURL

FormatFileDataURL as C (Key as C)

Return type: C

Arguments

Key as C The key of the file in the session-state collection. The value of key is a file name without any path components.

Context.Session.FormatFileDataURL() returns a URL suitable for a browser to retrieve a session file. No assumptions should be made about the construction of this URL. Check Context.Session.CallResult.Success before using the return value.

GetData

GetData as L (Key as C, ByRef Value as A)

Return type: L

Arguments

Key as C The key of the session-state variable to be retrieved.
ByRef Value as A A reference to a variable to receive the session-state variable value.

Context.Session.GetData() gets the value of a specific key from the session-state collection. Check Context.Session.CallResult.Success before using the return value.

GetDataFromFile

GetDataFromFile as L (Key as C, ByRef Value as B, Remove as L = .F.)
GetDataFromFile as L (ByRef Value as B, Key as C, Remove as L = .F.)

Return type: L

Arguments

Key as C The key of the session-state variable to be retrieved.
ByRef Value as B A reference to a variable to receive the session-state variable value.
Remove as L A setting of .T. or .F. to remove the item from the session-state collection after it has been retrieved. This is optional and defaults to .F..

Context.Session.GetDataFromFile() gets the value of a key from the session-state collection. Check Context.Session.CallResult.Success before using the return value.

GetSQLCredentials

GetSQLCredentials as L (ByRef Username as C, ByRef Password as C)

Return type: L

Arguments

ByRef Username as C The variable to receive the value of the SQL username.
ByRef Password as C The variable to receive the value of the SQL password.

Context.Session.GetSQLCredentials() if successful returns the SQL username and password used for SQL connections. See Session.GetSQLCredentails for more details. Check Context.Session.CallResult.Success before using the return value.

Remove

Remove as V (Name as C)

Return type: V

Arguments

Name as C The name of the session-state variable.

Context.Session.Add() removes a named value to the session-state collection. Check Context.Session.CallResult.Success before using the return value.

RemoveAll

RemoveAll as V ()

Return type: V

Arguments

None.

Context.Session.RemoveAll() is an alias of Context.Session.Clear(). Check Context.Session.CallResult.Success before using the return value.

RemoveAt

RemoveAt as V (Index as N)

Return type: V

Arguments

Index as N The index of the session-state variable to be removed. This index is zero based.

Context.Session.RemoveAt() removes the item at the specified 0-based index from the session-state collection. Check Context.Session.CallResult.Success before using the return value.

SaveData

SaveData as L (Key as C, Value as A)

Return type: L

Arguments

Key as C The key of the session-state variable to be retrieved.
Value as A The value of the session-state variable. Although type A, any type, is allowed it is deprecated for the value. The value should be of type C in order to support the most types of session-state providers under IIS.

Context.Session.SaveData() sets the value of a key in the session-state collection. Check Context.Session.CallResult.Success before using the return value.

SaveDataAsFile

SaveDataAsFile as L (FileName as C, Value as C, RemoveAfterFirstRetrieval as L = .T.)
SaveDataAsFile as L (FileName as C, Value as B, RemoveAfterFirstRetrieval as L = .T.)

Return type: L

Arguments

FileName as C The name of the file to be saved. This name should not have any path components.
Value as B The bytes to be saved.
Value as C The characters to be saved. The characters are converted to a UTF-8 stream of bytes that are saved.
RemoveAfterFirstRetrieval as T This is reserved for future use.

Context.Session.SaveDataAsFile() saves the value to the session-state collection under IIS. Under the stand-alone application server, the value is written to disk in the stand-alone application server's session folder. Check Context.Session.CallResult.Success before using the return value.

SaveFileToSessionFile

SaveFileToSessionFile as L (SourceFile as C, Key as C, RemoveAfterFirstRetrieval as L = .T.)

Return type: L

Arguments

SoureName as C The full path of the file whose contents are to be saved into the session-state collection.
Key as C The key for the data in the session-state collection. The value of key is a file name without any path components.
RemoveAfterFirstRetrieval as T This is reserved for future use.

Context.Session.SaveFileToSessionFile() saves the contents of the source file to the session-state collection under IIS. Under the stand-alone application server, the source file is copied to disk in the stand-alone application server's session folder. Check Context.Session.CallResult.Success before using the return value.

SaveSessionFileToFile

SaveSessionFileToFile as L (Key as C, DestinationFile as C)

Return type: L

Arguments

Key as C The key of the data in the session-state collection. The value of key is a file name without any path components.
DestinationFile as C The full path of the file into which the session-state data is to be saved.

Context.Session.SaveSessionFileToFile() saves the contents of the session-state key to the destination file under IIS. Under the stand-alone application server, the session file in the stand-alone application server's session folder is copied to the destination file. Check Context.Session.CallResult.Success before using the return value.

SetSQLCredentials

SetSQLCredentials as L (Username as C, Password as C)

Return type: L

Arguments

Username as C The value of the SQL username.
Password as C The value of the SQL password.

Context.Session.SetSQLCredentials() sets the SQL username and password used for SQL connections. See Session.SetSQLCredentails for more details. Check Context.Session.CallResult.Success before using the return value.

© Copyright Alpha Software Corporation 2000-2015