Class BudaEngine

Namespace

PolarStudio

Assembly

PolarStudio.dll

The core Engine of Polar Studio. There is only one single instance active of the Engine. All other object are created from here.

public class BudaEngine : PolarWeakEventListener

Inheritance

object

BudaEngine

Implements

PolarWeakEventListener

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

Globals.IsNumericType(object)

Constructors

BudaEngine(AppConfiguration)

Instanciate the Engine for a specific Configuration

public BudaEngine(AppConfiguration pConfiguration)

Parameters

pConfiguration AppConfiguration

The configuration to use

Properties

Certificate

The Certificate object that represents the Certificate for this server.

public PolarCertificate Certificate { get; }

Property Value

PolarCertificate

CertificateFileName

This read-only property returns the FileName of the current certificate as used for the Polar Studio license on this server.

public string CertificateFileName { get; }

Property Value

string

ConcurrentUsers

Returns the current number of logged-in users within the current server.

public int ConcurrentUsers { get; }

Property Value

int

Configuration

The Configuration for this project as defined in for example the file system.

public AppConfiguration Configuration { get; }

Property Value

AppConfiguration

DevelopmentMode

Returns a boolean indicating if running in DevelopmentMode or not.

public bool DevelopmentMode { get; }

Property Value

bool

DevelopmentModeVersion

When Developing, this property is non-zero (initialized with 1). Also, each time the project is refreshed, the DevelopmentModeVersion property will increase by one. When not developing, this value returns 0.

public int DevelopmentModeVersion { get; }

Property Value

int

HostName

The HostName in IIS for the current application. Can be empty.

public string HostName { get; }

Property Value

string

IdentiKey

The IdentiKey is unique for each server and is used in the Certificate for the Polar Studio license.

public string IdentiKey { get; }

Property Value

string

MaxConcurrentUsers

Returns the maximum allowed number of concurrent users based on various parameters, like the certificate and the configuration.

public int MaxConcurrentUsers { get; }

Property Value

int

MaxStateTransitionNoteLength

This property get the maximum length of state-transition notes.

public int MaxStateTransitionNoteLength { get; }

Property Value

int

PasswordComplexityCharCountAlpha

The minimal number of Alpha (A-Z) characters in the password in either upper or lower case

public int PasswordComplexityCharCountAlpha { get; set; }

Property Value

int

PasswordComplexityCharCountAlphaUpper

The minimal number of uppercase alpha (A-Z) characters in the password

public int PasswordComplexityCharCountAlphaUpper { get; set; }

Property Value

int

PasswordComplexityCharCountNumeric

The minimal number of Numeric (0-9) characters in the password

public int PasswordComplexityCharCountNumeric { get; set; }

Property Value

int

PasswordComplexityCharCountSpecial

The minimal number of special (@#$ etc) characters in the password

public int PasswordComplexityCharCountSpecial { get; set; }

Property Value

int

PasswordComplexityMinPasswordLength

This property gets/set the minimum password length. It has a hard-coded minimum value of 4 and an hard-coded maximum value of 32

public int PasswordComplexityMinPasswordLength { get; set; }

Property Value

int

PhysicalPath

The PhysicalPath property returns the location of the WebRoot in the file-system.

public string PhysicalPath { get; }

Property Value

string

ProjectFolder

The folder in the file system to store project-specific files. Was equal to the folder the BPP was stored in, but is now probably a specific folder set in the configuration file.

public string ProjectFolder { get; }

Property Value

string

ProjectPath

The Path for the current project. Was primarily used for BPP files.

public string ProjectPath { get; }

Property Value

string

Repository

The Repository object gives structured read-only access to all elements in the Polar Studio repository.

public repProject Repository { get; }

Property Value

repProject

RunningFromIDE

If running from Polar Studio, then RunningFromIDE will return True.

public bool RunningFromIDE { get; }

Property Value

bool

ScriptTimeOutSeconds

This property gets/sets the timeout for scripts in the project.

public int ScriptTimeOutSeconds { get; set; }

Property Value

int

SmartHost

The default SmartHost to use when sending out SMTP Emails. Can also contain portnumber, UserID/Password, like in: smtp.somehost.com:77 smtp.somehost.com;Benny;@lfa88 smtp.somehost.com;Benny;@lfa88;ssl Note: The password may not contain a semicolon (;) SSL is optional to ensure ssl communication and will by default use to port 465, unless another port is specified

public string SmartHost { get; set; }

Property Value

string

SpecialPasswordCharacters

This read-only property returns the special characters for passwords. It can be used to display these characters in the user interface.

public string SpecialPasswordCharacters { get; }

Property Value

string

TimeZones

Returns all TimeZones in the system.

public PolarTimeZones TimeZones { get; }

Property Value

PolarTimeZones

Variables

The Variables can be used to store custom information in the Engine

public Dictionary Variables { get; }

Property Value

Dictionary

VirtualDirectory

Returns the name of the VirtualDirectory in IIS if applicable

public string VirtualDirectory { get; }

Property Value

string

Methods

ActiveLanguages(bool)

Returns a string of the ID's of the languages set to Enabled in the repository, like "[0][2][3]"

public string ActiveLanguages(bool pReloadRepository = false)

Parameters

pReloadRepository bool

Returns

string

A coded string with the ID's of the enabled languages contained in square brackets. The value of the setting DefaultLanguage is always appended to the end, also enclosed in square brackets.

CheckPasswordComplexity(BudaSession, string)

This function checks the given pNewPassword and returns an error message with an explanation if the given password does not match the minimal complexity rules.

public string CheckPasswordComplexity(BudaSession pSession, string pNewPassword)

Parameters

pSession BudaSession

The current session

pNewPassword string

The new password to evaluate

Returns

string

A text indicating why the password does not comply to the rules or an empty string if no problems are found.

ClearErrorLog(DateTime)

To clear the contents of the ErrorLog. If a date/time is specified, all entries older that date/time are deleted and newer entries are kept.

public void ClearErrorLog(DateTime pDateTimeUntilWhichToClear = default)

Parameters

pDateTimeUntilWhichToClear DateTime

A DateTime. Older entries are deleted.

Exceptions

Exception

In case of an error, an Exception is thrown.

ClearLoginLog(DateTime)

To clear the contents of the LoginLog. If a date/time is specified, all entries older that date/time are deleted and newer entries are kept.

public void ClearLoginLog(DateTime pDateTimeUntilWhichToClear = default)

Parameters

pDateTimeUntilWhichToClear DateTime

A DateTime. Older entries are deleted.

Exceptions

Exception

In case of an error, an Exception is thrown.

CodedVersion()

The Version returns the version of the Assembly as a coded string, like '8.4.22'

public string CodedVersion()

Returns

string

ConvertBluePolarProjectFile(DataConnector)

This method is internally used within PolarStudio to convert a project to the newest structure.

public bool ConvertBluePolarProjectFile(DataConnector pDataConnector)

Parameters

pDataConnector DataConnector

The dataconnector to project's repository.

Returns

bool

A boolean indicating a convert has been executed.

Exceptions

Exception

Any error.

CreateSession()

Use CreateSession to create a new session. After creation, a login has to take place.

public BudaSession CreateSession()

Returns

BudaSession

New BudaSession

DecodeCodedQuery(string, BudaApplication, BudaDataSet)

This function is intended to be used internally by the engine. It decodes a coded query, thus it replaces #<= ... ># script expressions, and <PrivateRecordID> , <PrivateTableName> and <UserID>

public string DecodeCodedQuery(string pInputQuery, BudaApplication pApplication, BudaDataSet pContextDataSet = null)

Parameters

pInputQuery string

The SQL query to decode.

pApplication BudaApplication

The current Application

pContextDataSet BudaDataSet

The related DataSet this query is decoded for. Is used for running embedded scripts.

Returns

string

Destruct()

Destruct will free up resources.

public void Destruct()

ErrorLog(int)

Returns the ErrorLog as a Collection of Dictionaries with a max of the specified number of lines.

public Collection ErrorLog(int pNumberOfLines = 100)

Parameters

pNumberOfLines int

The maximum number of lines to retrieve. The technical max is set to 1000, the default is 100.

Returns

Collection

A Collection of Dictionaries

Exceptions

Exception

In case of an error, an Exception is thrown.

GetApplicationDataConnector(string)

To get a new DataConnector for the given ApplicationPID

public DataConnector GetApplicationDataConnector(string pApplicationPID)

Parameters

pApplicationPID string

The ApplicationPID to get the dataconnector for.

Returns

DataConnector

A new DataConnector to the database for the given ApplicationPID

GetContentType(string)

To get a specific HTTP-Content-Type for a given file-extension. If the FileExtension is a content-type (contains a forward slash) then the corresponding file extension is returned.

public string GetContentType(string pFileExtension)

Parameters

pFileExtension string

The file-extension to get the Content-Type for. If a Content-Type is passed (like 'text/xml') then the corresponding file-extension is returned

Returns

string

The content-type for the given file extension or the file-extension (whithout a dot) for the given content-type.

GetContext(object)

Gets the context for an object for calling ScriptEvaluate.

public Context GetContext(object pContextObject)

Parameters

pContextObject object

Returns

Context

GetCustomCodeModule(int, string)

This functions returns a CustomCode module to run custom modules

public CustomCodeModule GetCustomCodeModule(int pParentApplicationID, string pModuleCode)

Parameters

pParentApplicationID int

The ApplicationID this custom module is defined within.

pModuleCode string

The full source for the module.

Returns

CustomCodeModule

A CustomCodeModule object that can be used to run the custom scripts.

GetCustomCodeModule(int, string, ref string)

This functions returns a CustomCodeModule to run custom modules

public CustomCodeModule GetCustomCodeModule(int pParentApplicationID, string pModuleCode, ref string pErrorMessage)

Parameters

pParentApplicationID int

The ApplicationID this custom module is defined within. Use -1 for a 'global' based custom module

pModuleCode string

The full source for the module.

pErrorMessage string

If a compile error occurred when compiling the given ModuleCode, the ErrorMessage will contain the first compile error.

Returns

CustomCodeModule

A CustomCodeModule object that can be used to run the custom scripts.

GetFreeSessionSlots(int)

This method returns an overview of the free 'slots' for the user-management. For example, in case of a 10 user certificate, 10 slots will be available. With every log-on, one of these slots will be allocated. On log-off, the slot will be released.

public string GetFreeSessionSlots(int pMaxNumberOfSessions = 100)

Parameters

pMaxNumberOfSessions int

Returns

string

GetLogTime()

Helper function used internally to get the current time for the Log. Respects the setting 'LogTimesAsUTC' and returns either the local date/time or the UTC date/time accordingly.

public DateTime GetLogTime()

Returns

DateTime

A DateTime to use in the logs.

GetLookupCache(BudaApplication, int, bool, long, string)

LookupCaches are used to speed up getting the Identifiers for records in tables. Smaller tables are 'cached' completely when the LookupCache is initialized, larger tables are cached on-demand. Tables that have the property 'Cache lookup values' will in particular use a Lookup Cache, but also tables that have this property not set can use this feature.

public LookupCache GetLookupCache(BudaApplication pApplication, int pTableID, bool pClearCache = false, long pClearCacheRecordID = 0, string pIdentifier = "")

Parameters

pApplication BudaApplication

The ApplicationID

pTableID int

The TableID

pClearCache bool

To remove a record from the cache. It will be re-read the next time it is needed.

pClearCacheRecordID long

The RecordID of the record to be removed from the cache. Only applicable if pClearCache = True

pIdentifier string

A specific Identifier to get this cache for. The Identifier must be a SQL-expression returning a string to identify a record.

Returns

LookupCache

GetMessage(string, int, int, dynamic, string, string, string)

The base function to get a Message from Polar Studio

public string GetMessage(string pMessage, int pApplicationID, int pLanguageID, dynamic pContext = null, string pMessagesPath = "", string pMessagesProfile = null, string pDefaultValue = null)

Parameters

pMessage string

The full message to parse

pApplicationID int

The ApplicationID. Use -1 for global messages.

pLanguageID int

The LanguageID. Use -1 for DefaultText

pContext dynamic

The context for Script-expressions. If not pContext is given, embedded scripts will not be parsed

pMessagesPath string

Used internally to prevent circular references. Always pass an empty string.

pMessagesProfile string

The specific profile to get the message for.

pDefaultValue string

A default value for if the specifically requested message is not found.

Returns

string

The message.

GetScriptingHost()

To get the ScriptEngine used for this project.

public ScriptEngine GetScriptingHost()

Returns

ScriptEngine

The ScriptEngine

GetSetting(string, string)

Gets a named setting from the settings in the repository of Polar Studio

public string GetSetting(string pSettingName, string pDefaultValue = "")

Parameters

pSettingName string

The name of the setting (not case sensitive)

pDefaultValue string

The default value to use if the setting was not found.

Returns

string

ImplicitProcedureHeader(int, string)

This function returns a string for the implicit script with the given ProcedureName in the given Application(ID).

public string ImplicitProcedureHeader(int pApplicationID, string pProcedureName)

Parameters

pApplicationID int

The ApplicationID the script can be defined in. Give -1 for global scripts.

pProcedureName string

The bare name of the procedure.

Returns

string

An empty string if the script does not exist or has more than 1 parameter; ProcedureName if the script exists and has no parameters; ProcedureName if the script exists and has one parameter (regardless the name or type of that parameter)

LogError(string, string, string, string, string, int, string)

To Log an Error. Depending on the project, the error will be logged on the managment-server and/or using script-events. You can use the parameters however you need.

public void LogError(string pUserName, string pGroupName, string pApplicationName, string pTableName, string pRecordSource, int pErrorNumber, string pErrorMessage)

Parameters

pUserName string

nvarchar(100)

pGroupName string

nvarchar(100)

pApplicationName string

nvarchar(100)

pTableName string

nvarchar(100)

pRecordSource string

ntext

pErrorNumber int

Any number identifying the error. long (required)

pErrorMessage string

ntext

LoginLog(int)

Returns the LoginLog as a Collection of Dictionaries with a max of the specified number of lines.

public Collection LoginLog(int pNumberOfLines = 100)

Parameters

pNumberOfLines int

The maximum number of lines to retrieve. The technical max is set to 1000, the default is 100.

Returns

Collection

A Collection of Dictionaries

Exceptions

Exception

In case of an error, an Exception is thrown.

PasswordComplexityDescription(BudaSession, string)

This function returns a text describing the rules for new passwords, leave pSpecificMessageIdentifier to get all descriptions or use 'Length', 'Alpha', 'Numeric', 'Special' to get a specific message.

public string PasswordComplexityDescription(BudaSession pSession, string pSpecificMessageIdentifier = "")

Parameters

pSession BudaSession

The session

pSpecificMessageIdentifier string

If only one element is to be described. Use values 'Length', 'Alpha', 'AlphaUpper', 'AlphaLower', 'Numeric', 'Special',

Returns

string

ReleaseAllReportingEngines()

This method releases all Report Engines, so the definitions will be re-read from the stored XML file

public void ReleaseAllReportingEngines()

ReloadRepository(bool)

This method is to reload the repository.

public bool ReloadRepository(bool pReloadScriptEnvironmentOnly = false)

Parameters

pReloadScriptEnvironmentOnly bool

Can be set to True to only reset the scripting environment.

Returns

bool

Always returns True

ScriptEvaluate(object, string)

To run a script pExpression for the given pContext. No errors will be returned or thrown.

public object ScriptEvaluate(object pContext, string pExpression)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

Returns

object

The result of the script

ScriptEvaluate(object, string, ref bool)

To run a script pExpression for the given pContext. If a script error occurs, the ByRef parameter pScriptErrorOccurred will be set to True.

public object ScriptEvaluate(object pContext, string pExpression, ref bool pScriptErrorOccurred)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

pScriptErrorOccurred bool

A by-ref parameter that will be set to true if a script-error occurred.

Returns

object

The result of the script

ScriptEvaluate(object, string, ref bool, ref object)

To run a script pExpression for the given pContext. If a script error occurs, the ByRef parameter pScriptErrorOccurred will be set to True.

public object ScriptEvaluate(object pContext, string pExpression, ref bool pScriptErrorOccurred, ref object FunctionParameter0)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

pScriptErrorOccurred bool

A by-ref parameter that will be set to true if a script-error occurred.

FunctionParameter0 object

A byref object parameter that can contain any object to pass to the script as parameter. In the ScriptExpression, use 'FunctionParameter0' to refer to the passed object.

Returns

object

The result of the script

ScriptEvaluate(object, string, ref bool, ref object, ref string)

To run a script pExpression for the given pContext. If a script error occurs, the ByRef parameter pScriptErrorOccurred will be set to True.

public object ScriptEvaluate(object pContext, string pExpression, ref bool pScriptErrorOccurred, ref object FunctionParameter0, ref string pErrorMessage)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

pScriptErrorOccurred bool

A by-ref parameter that will be set to true if a script-error occurred.

FunctionParameter0 object

A byref object parameter that can contain any object to pass to the script as parameter. In the ScriptExpression, use 'FunctionParameter0' to refer to the passed object.

pErrorMessage string

A by-ref parameter that will be filled with the text of the error if applicable.

Returns

object

The result of the script

ScriptEvaluate(object, string, ref string)

To run a script pExpression for the given pContext. If a script error occurs, the error-text is passed in the ByRef parameter pErrorMessage

public object ScriptEvaluate(object pContext, string pExpression, ref string pErrorMessage)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

pErrorMessage string

A by-ref parameter that will be filled with the text of the error if applicable.

Returns

object

The result of the script

ScriptEvaluateImplicit(object, string)

To run an Implicit script. This function is called with only the bare name of the script. The script can have 1 parameter at most, being the pContext parameter. Depending on if this script is implemented, it will be called or not. There will be no error message is the script is not implemented. No script-errors will be returned.

public object ScriptEvaluateImplicit(object pContext, string pProcedureName)

Parameters

pContext object

The Context to run this script for.

pProcedureName string

The bare name of the script to run (without parameters).

Returns

object

The result of the implementation of the script (if any)

ScriptEvaluateImplicit(object, string, ref string)

To run an Implicit script. This function is called with only the bare name of the script. The script can have 1 parameter at most, being the pContext parameter. Depending on if this script is implemented, it will be called or not. There will be no error message is the script is not implemented.

public object ScriptEvaluateImplicit(object pContext, string pProcedureName, ref string pErrorMessage)

Parameters

pContext object

The Context to run this script for.

pProcedureName string

The bare name of the script to run (without parameters).

pErrorMessage string

A by-ref variable that will contain the text of a script-error if applicable.

Returns

object

The result of the implementation of the script (if any)

ScriptEvaluateImplicit_ReturnErrorMessage(object, string)

To run an Implicit script. This function is called with only the bare name of the script. The script can have 1 parameter at most, being the pContext parameter. Depending on if this script is implemented, it will be called or not. There will be no error message is the script is not implemented. In case of a script-error, the error-message is returned as script-result, else the result of the script is returned.

public object ScriptEvaluateImplicit_ReturnErrorMessage(object pContext, string pProcedureName)

Parameters

pContext object

The Context to run this script for.

pProcedureName string

The bare name of the script to run (without parameters).

Returns

object

The result of the implementation of the script (if any)

ScriptEvaluate_ReturnErrorMessage(object, string, bool)

To run a script pExpression for the given pContext. If a script error occurred, this errormessage will be returned (or, if pThrowErrorMessageAsException == True, it will be raised as an error)

public string ScriptEvaluate_ReturnErrorMessage(object pContext, string pExpression, bool pThrowErrorMessageAsException = false)

Parameters

pContext object

The Context to run the script for.

pExpression string

The script-expression to evaluate.

pThrowErrorMessageAsException bool

If this parameter is passed as True and a script-error occurs, an exeption is thrown instead of passing the error message as result.

Returns

string

The result of the script or the error-message if applicable.

Exceptions

Exception

If a script-error occurred and pThrowErrorMessageAsException == True, then an exception is thrown.

ScriptProcedureArguments(int, string, bool)

This is a helper function to get the number of arguments (parameters) for a given procedure.

public int ScriptProcedureArguments(int pApplicationID, string pProcedureName, bool pReturnRealNumberOfParameters = false)

Parameters

pApplicationID int

The ID for the application. Use -1 for global functions

pProcedureName string

The bare name of the procedure (without parameter or parenthesis)

pReturnRealNumberOfParameters bool

Will return the real number of parameters. Normally, if a procedure has more than 1 parameter, -1 is returned. If this parameter is set to True, the actual number of parameters is returned.

Returns

int

the number of parameters (arguments). Will return -1 if the procedure is not found or if the procedure has more than 1 parameter (and pReturnRealNumberOfParameters was False)

SendMail(string, string, string, string, string, string, object, string)

To send an Email using SMTP

public string SendMail(string pSender, string pRecipients, string pSubject, string pBodyText, string pCCrecipients = "", string pBCCrecipients = "", object pAttachments = null, string pSmartHost = "")

Parameters

pSender string

A valid email address representing the sender.

pRecipients string

zero, one or more Valid email addresses (semi-colon separated) where to send the email to. You can leave this parameter empty if you are BCC-ing the email.

pSubject string

The subject for the email

pBodyText string

The body for the email. The body can start with <HTML> for if you want to send an HTML formatted email

pCCrecipients string

zero, one or more Valid email addresses

pBCCrecipients string

zero, one or more Valid email addresses

pAttachments object

Attachments: array or collection of attachments: - an attachment is either: - a filename (that links to a file in the file-system) - FileName[;ContentType] & vbCrLf & FileData(as string) Start the filename with an exclamation-mark, for inline images

pSmartHost string

A host (server) used to send out the SMTP mail. Can also contain portnumber, UserID/Password, like in: smtp.somehost.com:77 smtp.somehost.com;Benny;@lfa88 smtp.somehost.com;Benny;@lfa88;ssl Note: The password may not contain a semicolon (;) SSL is optional to ensure ssl communication and will by default use to port 465, unless another port is specified If not SmartHost is given, the SmartHost from the configuration-file or the smarthost from the PolarServer.ini file is used.

Returns

string

An error message if applicable

UnEscapeIdentifier(string, BudaDataSet)

Identifiers in Polar Studio can contain pseudo functions NumberToString and DateToString. These functions are translated to specific SQL expressions that return a coded result for that date or number. To convert these coded results to user-readable texts, UnEscapeIdentifier is used on the coded Identifier result. The DataSet or the Session is passed to let the engine know which user-settings to use.

public string UnEscapeIdentifier(string pIdentifier, BudaDataSet pDataSet)

Parameters

pIdentifier string

The coded Identifier

pDataSet BudaDataSet

The DataSet as is used to determine the users date/time/number formatting settings.

Returns

string

User readable string

UnEscapeIdentifier(string, BudaSession)

Identifiers in Polar Studio can contain pseudo functions NumberToString and DateToString. These functions are translated to specific SQL expressions that return a coded result for that date or number. To convert these coded results to user-readable texts, UnEscapeIdentifier is used on the coded Identifier result. The DataSet or the Session is passed to let the engine know which user-settings to use.

public string UnEscapeIdentifier(string pIdentifier, BudaSession pSession)

Parameters

pIdentifier string

The coded Identifier

pSession BudaSession

The BudaSession as is used to determine the users date/time/number formatting settings.

Returns

string

User readable string

UnEscapeIdentifier(string, BudaUser)

Identifiers in Polar Studio can contain pseudo functions NumberToString and DateToString. These functions are translated to specific SQL expressions that return a coded result for that date or number. To convert these coded results to user-readable texts, UnEscapeIdentifier is used on the coded Identifier result. The DataSet or the Session is passed to let the engine know which user-settings to use.

public string UnEscapeIdentifier(string pIdentifier, BudaUser pUser)

Parameters

pIdentifier string

The coded Identifier

pUser BudaUser

The User as is used to determine the users date/time/number formatting settings.

Returns

string

User readable string

Version()

The Version returns the version of the Assembly as string, like '8.4 (Revision 22)'

public string Version()

Returns

string