2E API Reference
Overview
The APIs described in this section are the core of the Websydian Express 2E Developer, it is these APIs that gives the developer the means to interact with the Websydian Express framework and through that to send information to the user's browser and retrieve entered information from the browser.
The APIs are implemented as functions scoped under the file Websydian Express in the delivered 2E model and are imported into your own 2E model by using the YCPYMDLOBJ command.
Read more about the 2E model objects and the import process here.
You can also find basic information about each API in the narrative of the API function.
In the overview, the APIs are listed alphabetically. The following tables provides a functionality based overview of the APIs.
Core APIs
These are the base of the Websydian Express Developer, they include the APIs that are by far the most often used. Together with the Websydian Express runtime these APIs ensures that the developer can write values to the web page, retrieve entered values, transfer data from the function generating the page to the function handling events, and that the page can be sent to the browser.
Service APIs
These APIs are not strictly necessary. To a large degree they are just service functions that we during the development of examples and tutorial has found to be very nice to have. If you do not think they are sufficient or that they do not have the right behavior, you can for most of these APIs just develop your own functions (DateISO2Date7, Date2String, Date72DateISO, Numeric2String, String2Date, and String2Numeric).
Data APIs
These are APIs that all to some degree work on data from the Websydian Express database. The APIs provides the developer with the opportunity to extract information about sessions, users, authorization levels, folder lists, and sites. They also makes it possible for the developer to update the session and user tables used by Websydian Express.
AuthGetFirst - DEPRECATED
Type: Data/Authorization - DEPRECATED
Functionality:
The API is deprecated.
Usage:
Do not use this API.
The API will not be copied to your model in version 2.0 or later.
AuthGetNext - DEPRECATED
Type: Data/Authorization - DEPRECATED
Functionality:
The API is deprecated.
Usage:
Do not use this API.
The API will not be copied to your model in version 2.0 or later.
AuthLevelGet - DEPRECATED
Type: Data/Authorization - DEPRECATED
Functionality:
The API is deprecated.
Usage:
Do not use this API.
The API will not be copied to your model in version 2.0 or later.
CustomFldGetFirstInstance
Type: Data/Custom Fields
Functionality:
Set the file position and retrieves a record restricted by the parameters W2E/CustomFieldSiteKey, W2E/CustomFieldEntity, W2E/CustomFieldName, W2E/CustomFieldValue and positioned by W2E/PosCustomFieldInstanc.
To retrieve Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To retrieve Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The function returns a field W2E/CustomFieldInstance, which contains the unique identification of a record in the entity specified by the inputfield CustomFieldEntity (If the entity is ROLE - the returned identification is the RoleSurrogate, if the entity is USER - the returned identification is the UserID).
Usage:
Used together with CustomFldGetNextInstance to retrieve a list of records from a file (specified by W2E/CustomFieldEntity) that has the value specified by the parameter W2E/CustomFieldValue assigned to the custom field specified by the W2E/CustomFieldName parameter.
CustomFldGetFirstValue
Type: Data/Custom Fields
Functionality:
Set the file position and retrieves a record restricted by the parameters W2E/CustomFieldEntity, W2E/CustomFieldInstance and positioned by W2E/PosCustomFieldName.
To retrieve Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To retrieve Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The inputfield W2E/CustomFieldInstance specifies the unique identification of the record, which the custom fields and their values should be retrieved for (If the entity is ROLE - the identification is the RoleSurrogate, if the entity is USER - the identification is the UserID).
Usage:
Used together with CustomFldGetNextValue to retrieve a list of the custom fields defined for a record (specified by W2E/CustomFieldEntity and W2E/CustomFieldInstance) and the value assigned to each custom field. The custom fields are retrieved in custom field name order.
CustomFldGetNextInstance
Type: Data/Custom Fields
Functionality:
Retrieves the next record from the list defined by CustomFldGetFirstInstance.
To retrieve Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To retrieve Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The function returns a field W2E/CustomFieldInstance, which contains the unique identification of a record in the entity specified by the inputfield CustomFieldEntity (If the entity is ROLE - the returned identification is the RoleSurrogate, if the entity is USER - the returned identification is the UserID).
Usage:
Used together with CustomFldGetFirstInstance to retrieve a list of records from a file that has a specific value for a custom field.
CustomFldGetFirstInstance must always be called before calling CustomFldGetNextInstance.
CustomFldGetNextValue
Type: Data/Custom Fields
Functionality:
Retrieves the next record from the list defined by CustomFldGetFirstValue.
To retrieve Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To retrieve Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The inputfield W2E/CustomFieldInstance specifies the unique identification of the record, which the custom fields and their values should be retrieved for (If the entity is ROLE - the identification is the RoleSurrogate, if the entity is USER - the returned is the UserID).
Usage:
Used together with CustomFldGetFirstValue to retrieve a list of the custom fields and their values defined for a record.
CustomFldGetFirstValue must always be called before calling CustomFldGetNextValue.
CustomFldGetValue
Type: Data/Custom Fields
Functionality:
Retrieves the value for a custom field for a specific record.
To retrieve Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To retrieve Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The inputfield W2E/CustomFieldInstance specifies the unique identification of the record, which the custom fields and their values should be retrieved for (If the entity is ROLE - the identification is the RoleSurrogate, if the entity is USER - the returned is the UserID).
Usage:
Use this function when you need to know the information saved for a custom field.
In many cases, it is desirable to use this API to retrieve values for the current user. The identification of this user can be found using the API's GetSessionID and GetSessionData (using the output from GetSessionID as input) - the GetSessionData returns the outputfield W2E/UserID, which identifies the current user for the session. Map this field to W2E/CustomFieldInstance to get values for the current user.
CustomFldSetValue
Type: Data/Custom Fields
Functionality:
Sets the value for a custom field for a specific record.
To set Custom field values for the user entity, specify "USER" for the W2E/CustomFieldEntity field.
To set Custom field values for the role entity, specify "ROLE" for the W2E/CustomFieldEntity field.
The inputfield W2E/CustomFieldInstance specifies the unique identification of the record, which the custom fields and their values should be set for (If the entity is ROLE - the identification is the RoleSurrogate, if the entity is USER - the returned is the UserID).
Usage:
Use this function when you need to change/set the value for a custom field.
In many cases, it is desirable to use this API to set values for the current user. The identification of this user can be found using the API's GetSessionID and GetSessionData (using the output from GetSessionID as input) - the GetSessionData returns the outputfield W2E/UserID, which identifies the current user for the session. Map this field to W2E/CustomFieldInstance to set values for the current user.
DateISO2Date7
Type: Service
Functionality:
Converts a Date7 to an ISO date. If the date is invalid the return code is set to W2E/RC_INVALID_DATE and *loval is returned in DateISO.
Usage:
Used when you need to convert a Date7 to a DateISO. E.g. before calling the API Date2String.
Date2String
Type: Service
Functionality:
Converts an ISO date to a formatted string according to a format mask.
The DateMask parameter controls the format of the string according to the
following rules:
yyyy specifies the position of the year.
mm specifies the position of the month.
dd specifies the position of the day
All of these must be present for the mask to be valid.
Apart from yyyy mm dd, you can specify two separator
characters.
If you specify the Condition "Use dataareas" for the mask, the mask will be read from the dataarea WSYDDATMSK. (The value for this dataarea is defined during the installation of Websydian Express).
Usage:
Used when a DateISO field should be shown on a webpage - either as an output
field or as an input field for an event.
If you need to show a Date7 field as a string, use the
Date72DateISO API before calling this API.
If you use the datemask from the dataarea, and you want to show this datemask to the user, you can retrieve it using the GetDateMask API.
Date72DateISO
Type: Service
Functionality:
Convert a DateISO to a Date7
Usage:
Used when an ISO date has been returned by an API (e.g. String2Date) and the date need to be converted to a Date7 before being used to update the database.
DeletePresentationProp
Type: Data/Presentation
Functionality:
Deletes the specified property for the specified presentation.
Usage:
In many cases you will want to delete a property for the current presentation. You can retrieve the identification of this presentation by calling the GetCurrentPresentation API.
FldrLGet
Type: Data/Folder List
Functionality:
Retrieves information about the folder list specified by the parameter FolderListID.
Usage:
Called if information about the folder list is needed by the application. The
FolderListID is a unique identification of a folder list, and is usually
obtained from the session or user data. (E.g. by calling the
SessionGet, UserGet,
UserGetFirst, or UserGetNext
APIs).
FldrLGetFirst
Type: Data/Folder List
Functionality:
Sets the file position and retrieves the first folder list that belongs to the site specified by the LimSiteKey parameter. The PosName parameter is used to position the list (Ascending after W2E/Name).
Usage:
Used in combination with FldrLGetNext to retrieve a list of folder lists for a specific site. FldLGetFirst sets the file position in the folder list table.
Subsequent calls to FldrLGetNext will read the next records (ordered by name in ascending order).
FldrLGetID
Type: Data/Folder List
Functionality:
Retrieves information about a specific folder list based on the combination of site and name specified in the parameters W2E/Name and W2E/SiteKey (usr).
Usage:
Used to obtain further information about a folder list in situations where
the name of the folder list have been entered/selected by a user.
The Sitekey used will in most cases identify the current session. This Sitekey
can be found using the GetSessionData API.
FldrLGetNext
Type: Data/Folder List
Functionality:
Retrieves the next folder list in a sequence of folder lists established by an initial call to FldrLGetFirst.
Usage:
Used in combination with FldrLGetFirst to retrieve a list of folder lists for a specific site.
The function will return the next folder list in the list defined by the W2E/SiteKey
(usr) on the initial call to FldrLGetFirst.
The sequence of folder lists is ordered by name (ascending).
GetCurrentPresentation
Type: Data/Presentation
Functionality:
This API is used to retrieve the identification of the presentation currently being used and the data for this presentation and the process it belongs to.
Usage:
Apart from retrieving this information, you can use the returned presentation surrogate to retrieve or set properties for the presentation using the SetPresentationProperty, GetPresentationProperty, DeletePresentationProp, GetFirstPresentationProp, GetNextPresentationProp.
GetDateMask
Type: Service
Functionality:
Retrieve the DateMask (formatting) defined for the Websydian Express installation. This information is contained in the dataarea WSYDDATMSK. The information has been specified during the installation of Websydian Express.
Usage:
If a user should enter a date in the format specified by the DateMask in the dataarea, it is normally a good idea to show the DateMask to the user. By using this API, you can retrieve the value for the DateMask. Using the SetOutput API, you can write the value to the web page.
GetErrors
Type: Service
Functionality:
The GetErrors API makes a set of error messages thrown by another API available as a set of fields.
Usage:
Call the GetErrors API if you want to retrieve the specific error messages thrown by the APIs that can return more than one error (These can be recognized by having the field W2E/NumErrors as an output parameter - they include UserUpdate, UserCreate, SessionUpdate, SessionCreate).
The NumErrors parameter specifies how many of the 20 error messages that actually contain texts.
GetEventID
Type: Service
Functionality:
Returns the event ID (identification of the event) of the request being handled. The event ID is also the name of the EventHandler program that will handle the request.
Usage:
In some cases it can be necessary to load a page in different manners depending on the event that has been used to activate the page. This API can be called in the PageGenerator or in service functions to determine which event has originated the request.
GetFirstPresentationProp
Type: Data/Presentation
Functionality:
Retrieves the first property for a presentation.
Specify a presentation surrogate to identify which presentation you want to retrieve properties for. You can specify a start position for the list by providing a value for the input parameter W2E/PosPropName.
Usage:
This API is used together with GetNextPresentationProp to retrieve a list of all properties specified for a specific presentation. The properties are retrieved in property name order.
GetInput
Type: Core
Functionality:
Fetches the value of a web input field (input field for an event).
W2E/TypeName
Specifies the name of the input field for the event.
W2E/TypeValue
Specifies the field that is to receive the value entered in the input field.
Usage:
The function is called by the EventHandler. It fetches the value of the
specified web input field. If no web input field with the specified name
exists, a blank value is returned.
The web input values fetched by this API are the values entered by the user in
input fields in the browser.
GetNextPresentationProp
Type: Data/Presentation
Functionality:
Retrieves the next property for a presentation.
Usage:
This API is used together with GetFirstPresentationProp to retrieve a list of all properties specified for a specific presentation. The properties are retrieved in property name order.
GetParm
Type: Core
Functionality:
Gets the value for a parameter set by SetParm/SetGridParm when the HTML page was created. In addition to returning the value, the function also makes it possible to detect if the values have been changed since SetParm/SetGridParm was called.
W2E/TypeName:
Specifies the name of the parameter (The same name as used in the SetParm/SetGridParm API call).
W2E/Typevalue:
Specifies the field that must receive the value of the parameter.
Usage:
The function is called by the EventHandler.
The function must be called once for each field value set with the
SetParm/SetGridParm API when
the HTML page was generated.
After receiving all the parameters - and before doing any further handling of
the parameters - the ValidateParm API should be
called to ensure the integrity of the data (that they are unchanged compared to
the values written by the PageGenerator).
GetPresentation
Type: Data/Presentation
Functionality:
Retrieves information about a presentation. In addition to the presentation information, information about the process the presentation belongs to is also retrieved.
GetPresentationProperty
Type: Data/Presentation
Functionality:
Retrieves the value for a property for a presentation.
Usage:
Properties can be used to specify behavior for the process. This will often be used to retrieve properties for the presentation currently in use. The identification of this presentation can be retrieved using the GetCurrentPresentation API.
GetProcessParm
Type: Core
Functionality:
Gets the value specified for the parameter on the link generated by a menu service.
W2E/TypeName
Specifies the name of the parameter (the name specified on the menu service link specified in the template.
W2E/TypeValue
Specifies the field that must receive the value of the parameter.
Usage:
The function can be called in a ProcessEntryPoint if the process must be able to retrieve parameters specified on a menu service link.
The function must be called before calling the PageGenerator. Call this API once for each parameter that the business process must be able to retrieve.
GetSessionData
Type: Data/Session
Functionality:
Get information about the current session and the site used by the session.
Usage:
Used to obtain the information most commonly needed about the session specified by the parameter W2E/SessionID. If you want the information about the current session, use the GetSessionID API to obtain the W2E/SessionID.
GetSessionID
Type: Data/Session
Functionality:
Retrieves the identification of the session for the request being handled.
Usage:
Used by the function handling the request.
Fetches the identification of the session associated with the request.
This identification can be used to obtain further information about the session
(e.g. by calling the GetSessionData API). Or you
can use this ID as a foreign key in the database to uniquely identify the
session.
Numeric2String
Type: Service
Functionality:
Converts a value from a packed numeric field to a character string.
A number of parameters controls the format of the resulting string:
W2E/FormatSeparator:
CND Use Dataareas ('D') = the thousand and decimal separators will be read from the dataareas WSYDTHUSEP and WSYDDECSEP. These values will be used to format the string.
CND Use Dtaaras - no Thousand ('T') = the decimal separator will be read the dataarea WSYDDECSEP. No thousand separator will be inserted.
All other values = The separators specified in the input parameters W2E/ThousandSeparator and W2E/DecimalSeparator will be used.
W2E/ShowZero:
CND Yes = A 0 will be returned for the integer part of the number if the value of the number is between -1 and 1.
CND No = The integer part of the number will be blank if the value of the number is between -1 and 1. E.g: 0 = '', 0.2 = '.2'.
W2E/ThousandSeparator:
If W2E/FormatSeparator is "Use Dataareas" or "Use Dataareas - no Thousand" - this parameter is disregarded.
If W2E/FormatSeparator is not "Use Dataareas" or "Use Dataareas - no Thousand" - any value specified for this parameter will be used as thousand separator. If no thousand separator should be used - specify *BLANK as value.
W2E/Decimal Separator:
If W2E/FormatSeparator is "Use Dataareas" or "Use Dataareas - no Thousand" - this parameter is disregarded.
If W2E/FormatSeparator is not "Use Dataareas" or "Use Dataareas - no Thousand" and if the number is not an integer - this parameter must be specified. The specified value will be used as decimal separator.
W2E/NumberOfDecimals:
Specifies the number of decimals the resulting string will have (number of digits after decimal point).
Usage:
Use this function before calling the SetOutput/SetGridOutput APIs when the value of numeric fields should be shown on a web page.
If this value has been used to format a string shown for an input field for an event, it is recommended to use the API String2Numeric to parse the string retrieved by the GetInput API in the EventHandler.
ReloadSitePage
Type: Core
Functionality:
This API generates an HTML page that contains an event that reloads the site.
This event is executed automatically when the page is sent to the browser.
This page is generated by using the delivered WSLOAD template. This template
must be located in a folder in the folder list for the session for the event
to work.
Usage:
The function is called when the program handling a request must reload the
site. This will for example happen in a custom-made login function,
after the session is updated with the user and roles, the site should be
reloaded so that it reflects the new authorization.
This is done by calling this API.
After calling ReloadSitePage, the calling program should terminate - do not call
the WritePage API, as a page has already been sent to the browser.
RoleClearIntranet
Type: Data/Role
Functionality:
Removes the intranet restriction from the specified role.
Usage:
Calling this API makes the site elements authorized by the specified role available for sessions that originate outside the intranet.
RoleCreate
Type: Data/Role
Functionality:
Validates and creates a new Role.
If the input field W2E/ValidateOnly is set to VALIDATE, the function only
performs the validation. If UPDATE is specified, both the validation and the
creation is performed.
The function returns the number of errors encoutered (if any). You can use the
GeErrors API to retrieve a text for each error.
Usage:
Used if a business process (e.g. a custom Role maintenance suite) needs to create a Role.
RoleDelete
Type: Data/Role
Functionality:
Validates whether a Role can be deleted - and deletes the Role if the
validation is successful.
If the inputfield W2E/ValidateOnly is set to VALIDATE, only the validation is
performed. If UPDATE is specified, the validation is performed and the record is
deleted if the validation is successful.
Usage:
Used if a business process (E.g. a Custom Role maintenance suite) need to
delete a Role.
Pease note that a Role can't be deleted if it is referenced by Users or Site
Elements.
RoleGet
Type: Data/Role
Functionality:
Retrieves information about a specific role.
Usage:
This can be used if a RoleSurrogate (Unique identification of the role) is known and e.g. the name of the role is needed.
RoleGetByName
Type: Data/Role
Functionality:
Reads a specific role based on the site and the name of the role.
Usage:
Can be used to find additional information about a role (e.g. the RoleSurrogate) if only the name of the role is known.
RoleGetFirst
Type: Data/Role
Functionality:
Retrieves the first role for the specified site. The roles are retrieved in role name order. It is possible to position the read by using the input parameter W2E/PosRoleName.
Usage:
Used together with the API RoleGetNext to retrieve a list of the roles for a Site.
RoleGetNext
Type: Data/Role
Functionality:
Retrieves the next role for the specified site. The roles are retrieved in role name order. The first role is fetched and the position of the roles are established by calling the RoleGetFirst API.
Usage:
Used together with the API RoleGetFirst to retrieve a list of the roles specified for a specific site.
You must always call RoleGetFirst before calling RoleGetNext.
RoleIsInIntranet
Type: Data/Role
Functionality:
Checks whether the Role is allowed to be used by Sessions that does not originate from the Intranet.
Usage:
Used if you need to check whether the Role is specified as being for intranet use only.
RoleSetInItranet
Type: Data/Role
Functionality:
Specifies that the Role can only be assigned to sessions originating in the intranet.
Usage:
Use this API to specify that the Role should only be available for intranet sessions. When a Role has IntranetOnly set to yes, the role is not assigned to sessions originating outside the intranet, even though the user has the role assigned.
RoleUpdate
Type: Data/Role
Functionality:
Validates and updates the Role information.
If the inputfield W2E/ValidateOnly is set to VALIDATE, only the validation is
performed. If the value is UPDATE, both validation and update is performed.
Usage:
Used if a business process (e.g. a custom Role maintenance suite) needs to update a Role.
SessionAddRole
Type: Data/Session
Functionality:
Adds a role to the specified session. This provides further authority to the session.
Usage:
Can be used if a business process must add authorization to a session. This can for example be relevant if a user by providing additional information about himself can obtain access to parts of the sites he previously did not have access to.
SessionCreate
Type: Data/Session
Functionality:
Validates and creates the session specified in the input.
The parameter W2E/ValidateOnly controls whether the record is updated - or only the validation is performed.
CND VALIDATE = The data will only be validated - no record will be created.
CND UPDATE = If the validation is successful a record will be created
The parameter W2E/NumErrors specifies the number of errors found in the
validation. A text for each of these errors can be obtained by calling the
GetErrors API.
The function sets *Return Code to a non-normal value if errors are found in the
validation or if errors happens in the subsequent update.
Usage:
Used if the application needs to create a session. E.g. if an external application needs to simultaneously create a Websydian Express session and a session for another system.
SessionGet
Type: Data/Session
Functionality:
Retrieves the most basic information about the session specified by the
parameter W2E/SessionID.
Usage:
Used to obtain the most basic information about the session specified by the parameter W2E/SessionID. This will often be the current session. The W2E/SessionID can for the current session can be found using the GetSessionID API.
The difference between this API and the GetSessionData API is that this function does not resolve information about the site.
SessionGetAuth - Deprecated
Type: Data/Session
Functionality:
The API is deprecated.
Usage:
Do not use this API.
The API will not be copied to your model in version 2.0 or later.
SessionGetFirstRole
Type: Data/Session
Functionality:
Retrieves the first role that is assigned to the session. It also sets the position for further reads using the SessionGetNextRole API.
Usage:
Together with the SessionGetNextRole API this function can be used to create
a list of the roles currently assigned to a session.
This API must always be called before calling the SessionGetNextRole API.
SessionGetNextRole
Type: Data/Session
Functionality:
Retrives the next role that is assigned to the session.
Usage:
Together with the SessionGetFirstRole API, this function can be used to
create a list of the roles currently assigned to a session.
The SessionGetFirstRole must always be called before calling this API.
SessionIsRoleAuthorized
Type: Data/Session
Functionality:
Sets the *Return Code to *Normal if the specified session is authorized by the specified role. Otherwise the function will return an error.
Usage:
Used if you want to control functionality in your business processes based on the roles assigned to the session. E.g. only showing certain information if the session has a specific role assigned.
SessionRefreshFolderList
Type: Data/Session
Functionality:
Refreshes the folder list assigned to the session based on the currently assigned roles and user.
Usage:
This API can be used to let Websydian Express decide on the folder list the
session must use based on the roles and user assigned to the session.
It might be used in cases where you e.g. have assigned additional roles to the
session using the SessionAddRole API.
SessionRemoveAllRoles
Type: Data/Session
Functionality:
Removes all roles from the session.
Usage:
Can be used in custom-made log off functionality to remove all authorization from the session.
SessionRemoveRole
Type: Data/Session
Functionality:
Removes a role from a session. If the session does not have the role assigned, nothing happens.
Usage:
Can be used to reduce the authorization of a session.
SessionSetAnonymous
Type: Data/Session
Functionality:
Sets the session authorization based on the Anonymous User registered on the
site settings. Roles and folder list are assigned to the Session, the User ID is
set to 0.
If a user is already assigned to the session, an error is returned and no
updates are performed.
Usage:
Can be used to reset the "anonymous" settings for a session.
SessionSetFolderList
Type: Data/Session
Functionality:
Updates the folder list for the session. The folder list is set irrespective of the roles assigned to the session - overriding the normal assignment of folder lists to sessions.
Usage:
You can use this to change the folder list without updating user or roles for the session.
SessionSetUserAndUpdate
Type: Data/Session
Functionality:
Sets the user for the session and updates the roles and folder list for the session based on the specified user.
Usage:
Can be used to implement your own login functionality.
SessionUpdate
Type: Data/Session
Functionality:
Validates and updates the session specified in the input.
The parameter W2E/ValidateOnly controls whether the record is updated - or only the validation is performed.
CND VALIDATE = The data will only be validated - no record will be created.
CND UPDATE = If the validation is successful a record will be created
The parameter W2E/NumErrors specifies the number of errors found in the validation. A text for each of these errors can be obtained by calling the GetErrors API.
The function sets *Return Code to a non-normal value if errors are found in the validation or if errors happens in the subsequent update.
Usage:
Used if the application needs to update a session. E.g. in a special login function.
SetGridOutput
Type: Core
Functionality:
Sets the value for an output field in the grid in an HTML page.
W2E/TemplateName:
Specifies the name of the template that will be used to create the page.
W2E/GridRow:
Specifies the row in the grid that the value must be shown in.
W2E/TypeName:
Specifies the name of the replacement marker the value will replace in the template.
W2E/TypeValue:
The value that will be used to replace the replacement marker.
Usage:
The function is normally called in the PageGenerator function or in a load grid function called by the PageGenerator.
SetGridParm
Type: Core
Functionality:
Writes a parameter to a grid event in the HTML page. The value of the
parameter can be read by the program handling the event.
The parameter value is secured. This means that if it is changed illegally, then
the program handling the event will be able to detect this.
W2E/TemplateName:
Specifies the name of the template that will be used to create the web page.
W2E/GridRow:
Specifies the row in the grid the event which the parameter is written to belongs to.
W2E/EventID:
Specifies the event which the parameter is transferred to. This ID is the source name of the EventHandler function.
W2E/TypeName:
Specifies the name of the parameter
W2E/TypeValue:
Specifies the value of the parameter
Usage:
The function is called by the PageGenerator or by a Load Grid function that
is called by the PageGenerator.
The function offers the possiblity to transfer parameters from the program
generating the page to the program handling the request. (PageGenerator and
EventHandler).
The function must be called once for each parameter that must be transferred to
the program handling the event.
For each SetGridParm call that is made for an event (in the PageGenerator), a
GetParm call must be made in the EventHandler. These
GetParm calls must be followed by a call to the
ValidateParm API to verify the integrity of the data
received by the GetParm API (check that the retrieved
values are the same as the ones set by the PageGenerator).
SetOutput
Type: Core
Functionality:
Sets the value for an output field in the detail part of an HTML page.
W2E/TemplateName:
Specifies the name of the template that will be used to create the page.
W2E/TypeName:
Specifies the name of the replacement marker the value will replace in the template.
W2E/TypeValue:
The value that will be used to replace the replacement marker.
Usage:
The function is typically called in the PagGenerator. The function is called when a value must be specified for an output field or an input field for an event placed in the detail (non-grid) part of the page.
SetParm
Type: Core
Functionality:
Writes a parameter to a detail event in the HTML page. The value of the parameter can be read by the program handling the event.
The parameter value is secured. This means that if it is changed then the program handling the event will be able to detect this.
W2E/TemplateName:
Specifies the name of the template that will be used to create the web page.
W2E/GridRow:
Specifies the row in the grid the event which the parameter is written to belongs to.
W2E/EventID:
Specifies the event which the parameter is transferred to. This ID is the source name of the EventHandler function.
W2E/TypeName:
Specifies the name of the parameter.
W2E/TypeValue:
Specifies the value of the parameter.
Usage:
The function is typically called by the PageGenerator.
The function offers the possiblity to transfer parameters from the program generating the page to the program handling the request that is created when the event is activated by a user. (PageGenrator and EventHandler).
The function must be called once for each parameter that must be transferred to the program handling the event.
For each SetParm call that is made for an event (in the PageGenerator), a GetParm call must be made in the EventHandler.
These GetParm calls must be followed by a call to the ValidateParm API to verify the integrity of the data received by the GetParm API (check that the values are the same as the ones set by the PageGenerator).
SetPresentationProperty
Type: Data/Presentation
Functionality:
Used to set a property for a presentation programmatically (properties can also be set using the administration interface process maintain presentation (accessed through the business process maintenance)).
Usage:
Properties can be used to specify behavior for the process. This API will often be used to set properties for the presentation currently in use. The identification of this presentation can be retrieved using the GetCurrentPresentation API.
SiteGet
Type: Data/Site
Functionality:
Retrieve basic information about a Websydian Express site
Usage:
Can be used in special situations where information from the site is
necessary to execute the application logic.
An example could be that a link reloading the site should be inserted on a page
in certain circumstances. By reading the EntryURL from the site and setting this
using the SetOuput API it is possible for the developer
to create this link.
String2Date
Type: Service
Functionality:
Converts a formatted datestring to an ISO date - the entered date must conform to the format mask specified in the parameter W2E/DateMask.
W2E/Datemask controls the format according to the following rules:
yyyy specifies the position of the year.
mm specifies the position of the month.
dd specifies the position of the day.
All of these must be present for the mask to be valid.
If you specify the condition (CND) "Use dataareas" (value: 'D') for the mask, the mask will be read from the dataarea WSYDDATMSK. This dataarea contains the date format specified for the Websydian Express installation (specified during the installation).
Usage:
Used when the value for an ISO date field has been retrieved as a string using the GetInput/GetParm APIs - and the values should be converted to an ISO date before being used to e.g. update the database. This will normally be done in the EventHandler functions.
If your database/business field is a Date7 instead of a DateISO, use the API DateISO2Date7 after calling this API to get the string converted to Date7.
String2Numeric
Type: Service
Functionality:
Converts a formatted string into a numeric field based on a number of parameters.
W2E/Format of InputString:
CND Use Dataareas ('D'):
The thousand and decimalseparators will be read from the dataareas WSYDTHUSEP and WSYDDECSEP. These values will be used to parse the string.
All other values:
The values for the parameter fields W2E/ThousandSeparator and W2E/DecimalSeparator will be used to parse the string.
W2E/ThousandSeparator:
If W2E/Format of InputString is "Use dataareas" this parameter will be disregarded.
If W2E/Format of InputString is not "Use dataareas", the value specified for this parameter will be used as thousand separator when the string is parsed.
W2E/DecimalSeparator:
If W2E/Format of InputString is "Use dataareas" this parameter will be disregarded.
If W2E/Format of InpuString is not "Use dataareas", this value will be used as decimal separator when the string is parsed.
Usage:
Use this API in the EventHandler functions when a numeric value is fetched by the GetInput/GetParm functions.
UserAddRole
Type: Data/User
Functionality:
Adds a role to the users authorization.
Usage:
Can be used if a business process needs to add authorization to the user.
This can e.g. be relevant if a user agrees to a disclaimer or gives some
additional information that results in the user gaining additional
authorization.
Note that this is a permanent addition of authorization - if you just want to
add authorization for the current session, use the SessionAddRole API instead.
UserCheckPwd
Type: Data/User
Functionality:
Compares the entered password with the stored value.
Usage:
Used if a specialized login functionality is developed - or if specific events must be confirmed by the user reentering his password.
UserChgStatus
Type: Data/User
Functionality:
Change the state of an existing user profile.
W2E/ValidateOnly:
CND VALIDATE
The change of status will be validated - but the data will not be updated.
CND UPDATE
The status of the user will be changed to the specified value if the validation is successful.
Usage:
Used if a specialized user maintenance is developed. E.g. if a special process is developed allowing persons not having access to the Websydian Express administration interface to reactivate users.
UserCreate
Type: Data/User
Functionality:
Creates a user profile for a specific site.
W2E/ValidateOnly:
CND VALIDATE
The specified user data will be validated - but the data will not be updated.
CND UPDATE
The user will be created if the validation is successful.
W2E/UserID:
The function returns the unique identification of the created user.
W2E/NumErrors:
If the validation encounters errors, the *Return Code is set to a non-normal value and the field W2E/NumErrors will contain the number of errors encountered. You can use the GetErrors API to obtain a text for each of these errors.
Usage:
Used when custom registration of users is developed. E.g. if a user
self-registration process or a specialized registration of users for
several systems is created.
UserDelete
Type: Data/User
Functionality:
Deletes an existing user profile.
W2E/ValidateOnly:
CND VALIDATE
It is validated whether the deletion can happen - but the record is not deleted.
CND UPDATE
It is validated whether the deletion can happen. If the validation is successful, the record is deleted.
Usage:
Used when customized user maintenance functionality is been developed for the application.
UserGet
Type: Data/User
Functionality:
Retrieve basic information about a specific user profile, based on the unique identification of the user.
Usage:
Used whenever an application needs information about a specific user. E.g. if
the name of the user presently logged in should be shown on a
page. The identification of a user for a specific session can be found by
calling the GetSessionData API.
UserGetFirst
Type: Data/User
Functionality:
Sets the file position and retrieves the first user from that position.
The sequence of users will always be limited to users for a specific site (specifed by the W2E/SiteKey (usr) parameter).
W2E/LimitAuthLevel
By entering a non-zero value for the parameter W2E/LimAuthLevel, the sequence is limited to users having the specified authorization level.
W2E/LimFldrListID
By entering a non-blank value for the parameter W2E/LimFldrListID, the sequence is limited to users having the specified Folder list.
W2E/LimCreatedBy
By entering a non-zero value for the parameter W2E/LimCreatedBy, the sequence will be limited to users having been created by the specified user.
W2E/LimEMail
By entering a non-blank value for the parameter W2E/LimEMail, the sequence will be limited to users having the specified e-mail.
W2E/LimStatus
By entering a value for the parameter W2E/LimStatus the sequence is limited to users in the specified state.
The sequence of users is ordered by login name (ascending).
Usage:
Used together with the UserGetNext function to retrieve a list of users for a specific site.
UserGetID
Type: Data/User
Functionality:
Retrieves the unique identification of a user profile, based on the combination of the site key and the login name for the user.
Usage:
Used if the unique identification of the user table is needed for calls to other APIs (e.g. UserUpdate/UserDelete etc.) - but only the LoginName is available.
UserGetNext
Type: Data/User
Functionality:
Gets the next occurrence of users in the sequence established by an initial call to UserGetFirst.
Usage:
Used together with the UserGetFirst function to retrieve a list of users for a specific site. UserGetFirst is used to set the file position. Then UserGetNext is used to fetch further records.
UserGetNext will set *Return Code to W2E/RC_NOT_FOUND when the end of the list is reached.
UserIncrementFailedLogin
Type: Data/User
Functionality:
Add 1 to the number of failed logins registered for the user.
Usage:
Can be used as part of a custom-made login functionality. Call this API if
you register a failed login attempt for a user - and you want to inactivate the
user after a number of failed logins.
Please note that the user is NOT inactivated by this API. When you want to
inactivate the user, call the UserChgStatus API. To obtain the current number of
failed login attempts for a user, use the UserGet API.
UserIsAuthForRole
Type: Data/User
Functionality:
Checks whether the user is authorized for a specific role.
Usage:
Use this API if you want to control a business process based on the roles assigned to the user.
You can call the SessionIsRoleAuthorized API if you want to check the roles assigned to the session instead of the roles assigned to the user.
UserRemoveAllRoles
Type: Data/User
Functionality:
Removes all roles for a user.
Usage:
Can be used if a business process must delete a user. As a user can't be deleted if he has any roles assigned, this API must normally be called before deleting the user.
UserRemoveRole
Type: Data/User
Functionality:
Removes a specific role from a user.
Usage:
Can be used if a business process must remove authorization from a user.
UserResetFailedLogin
Type: Data/User
Functionality:
Set the current number of failed logins for a user to zero.
Usage:
Can be used as part of a custom-made login functionality. Should be called after a successful login by a user.
UserRoleGetFirst
Type: Data/User
Functionality:
Retrieves the first role for a specific user. Sets the position for retrieving the rest of the roles.
Usage:
Used together with the UserRoleGetNext API to retrieve a list of the roles assigned to the user (ordered by role name). The beginning of the list can be positioned by specifying a value for the parameter W2E/PosRoleName.
UserRoleGetNext
Type: Data/User
Functionality:
Retrieves the next role for a specific user.
Usage:
Used together with the UserRoleGetFirst API to retrieve a list of the roles
assigned to the user (ordered by role name).
The UserRoleGetFirst API must be called before calling this API.
UserUpdate
Type: Data/User
Functionality:
Updates an existing user profile.
W2E/ValidateOnly:
CND VALIDATE
The data will only be validated - the user record will not be updated.
CND UPDATE
The data will be validated and the user record will be updated if the validation is successful.
W2E/NumErrors:
If the validation encounters errors, the *Return Code is set to a non-normal value and the field W2E/NumErrors will contain the number of errors encountered. You can use the GetErrors API to obtain a text for each of these errors.
Usage:
Used if custom user maintenance is developed.
UserUpdatePwd
Type: Data/User
Functionality:
Update the password for a user profile
W2E/ValidateOnly:
CND VALIDATE
The data will only be validated - the user record will not be updated.
CND UPDATE
The data will be validated and the user record will be updated if the validation is successful.
Usage:
Used if a specialized function for changing the password for a user is developed. E.g. a function where the user can change his own password.
This function ensures that the password is stored as a signed value instead of clear text. This is necessary for the basic Websydian Express login functionality to work.
ValidateParm
Type: Core
Functionality:
The function checks the integrity of all the parameters that have been fetched using the GetParm method (for the current request).
Usage:
The API is called by the EventHandler.
The API must be called whenever the event being handled is using secure parameters (parameters set by SetParm/SetGridParm APIs).
The function must be called AFTER the value of each of these parameters has been fetched using the GetParm function.
The function must be called before doing any further handling of the data.
If an error indicating that the signature is wrong is returned by the
function, the handling of the request must be stopped and an error page
shown to the user.
WriteErrorPage
Type: Core
Functionality:
Generates an error page that is sent to the browser.
Usage:
The function can be called when the program handling a request encounters an error that must interrupt the handling of the request.
After calling WriteErrorPage, the calling program should terminate.
You can change the design of the error page by changing the template WSYDERP.
You do not have to use this API to make an error page. If you want to create your own error page, just create it as a normal PageGenerator function (in this way you have full control over the data being shown on the page).
WriteLog
Type: Service
Functionality:
Writes an entry to the Websydian Express message log.
Usage:
Used if the application should write a message to the Websydian Express message log.
The messages can be seen using the Message log menu item in the administration interface.
WritePage
Type: Core
Functionality:
The function generates an HTML page and sends the generated page to the browser.
The page is generated from the HTML template specified by the W2E/TemplateName input parameter.
Usage:
The function is called by the PageGenerator.
Before calling the WritePage API, the values that is to be used to substitute the replacement markers in the template must have been specified the SetOutput and SetGridOutput APIs.
Any parameters transferred by the events defined for the page must have been set using the SetParm and SetGridParm APIs.
Error Codes
The API's can encounter a number of error conditions. For each of these conditions, the API will return a Condition value in the *Return Code field.
This list shows the File value for each of these conditions - and has a short description of each error.
WEX0081 - W2E/RC_UNKNOWN
Returned when an unexpected error has occurred in a low-level function.
Example: An object is missing from the runtime library.
WEX0082 - W2E/RC_NOT_FOUND
Returned by APIs retrieving data if no record could be found based on the entered selection criteria.
This is not necessarily an error - in many cases, it is quite acceptable that a record does not exist for a specified key.
WEX0083 - W2E/RC_NO_FLD_NAME
Returned if an API that has a mandatory input parameter specifying a field name has been called with a blank name.
Solution: Ensure that a value is specified for the field name input parameter.
WEX0087 - W2E/RC_INVALID_SES
Returned if an invalid session id (typically 0/blank) has been specified as input or retrieved from a request.
Solution: Ensure that a value is specified for the session id parameter.
WEX0088 - W2E/RC_NO_KEY
Returned if the low level API checking integrity of the received parameters has not been able to find the key used to check the value.
Solution: Check the integrity key site setting for the current site in the administration interface.
WEX0090 - W2E/RC_NO_TEMPLATE
Returned if an API that has a mandatory input parameter specifying a template id has been called with a blank id.
Solution: Ensure that a value is specified for the template parameter.
WEX0114 - W2E/RC_INVALID_SIGN
The function validating the parameters retrieved from the request has found that the values of the parameters is not correct.
In a development situation this will typically mean that the SetParameter and the GetParameter calls for the event does not match.
In a production environment, this will typically mean that an attempt to tamper with the parameters for the event has occurred.
WEX0115 - W2E/RC_NO_GRIDROW
Returned if an API that has a mandatory input parameter specifying a row in a grid has been called with an invalid row number (0 or negative row number).
Solution: Specify the current row in the grid for the grid row parameter.
WEX0116 - W2E/RC_NO_EVENTID
Returned if an API that has a mandatory event id input parameter has been called with a a blank id.
WEX0118 - W2E/RC_SES_READ_ERR
Returned when an API has needed to access information for the current session - but have encountered an error when trying to read the session data.
Check whether the joblog for the application service jobs provides more information.
WEX0119 - W2E/RC_CRT_FAILED
Returned when an API creating new records in the Websydian Express database has encountered an error that prevented the record from being created.
Check whether the joblog for the application service jobs provides more information.
WEX0120 - W2E/RC_UPD_FAILED
Returned when an API updating records in the Websydian Express database has encountered an error that prevented the record from being updated.
Check whether the joblog for the application service jobs provides more information.
WEX0121 - W2E/RC_VAL_FAILED
Returned when an API has been called in the validation mode (ValidateOnly = VALIIDATE) - and the validation has registered one or more errors.
WEX0122 - W2E/RC_DLT_FAILED
Returned when an API deleting records in the Websydian Express database has encountered an error that prevented the record from being deleted.
Check whether the joblog for the application service jobs provides more information.
WEX0123 - W2E/RC_READ_FAILED
Returned when a function reading data from the Websydian Express database has encountered an error when trying to read the data. Please note that this is different from the RC_NOT_FOUND return code (which means that the record has not been found - but no errors occurred during the read).
Check whether the joblog for the application service jobs provides more information.
WEX0124 - W2E/RC_PWD_FAILED
Returned by the UserCheckPwd function if the entered password does not correspond to the one registered for the user.
WEX0125 - W2E/RC_GETNEXT_ERR
A GetNext function has been called without any calls being made to the corresponding GetFirst function.
Solution: Ensure that the corresponding GetFirst... API is called before calling the GetNext... API.
WEX0126 - W2E/RC_CAT_INVALID
An invalid category has been specified for a call to the WriteLog API.
Solution: Specify one of the valid values for the category (See the values specified for the field "W2E/Category of Message").
WEX0127 - W2E/RC_NO_MESSAGE
The WriteLog API has been called without any message being specified.
Solution: Specify a message to write to the log.
WEX0128 - W2E/RC_CALL_FAILED
A call to a program/serviceprogram has failed (typically as a PSDS error). More information will often be available in the Websydian Express message log and the OS400 joblog.
WEX0129 - W2E/RC_INVALID_PWD
A function updating the password for a user have been called with an invalid value (typically blank) for the password.
Solution: Ensure that a valid value is specified for the password.
WEX0163 - W2E/RC_DATAAREA_READ_ERR
The service functions used to format numeric or date fields could not read a necessary dataarea.
Solution: Check the library list for the application service jobs. The dataareas WSYDDECSEP and WSYDTHUSEP must be available for the application.
The installation places these dataareas in the express database library.
WEX0164 - W2E/RC_SAME_SEPARATOR
The same separator character has been specified for the thousand separator and the decimal separator.
Solution: If the separators are specified by the input parameters, ensure that different values are specified for decimal and thousand separator. If "Use dataareas" are specified, ensure that the separators specified in WSYDDECSEP (decimal separator) and WSYDTHUSEP (Thousand separator) are not the same.
WEX0165 - W2E/RC_TWO_DECIMAL_SEP
The string contains more than one decimal separators. The format function can't format the textstring when more than one decimal separator is specified.
WEX0166 - W2E/RC_INVALID_NUMBER
The string contains invalid (non-numeric) characters.
WEX0167 - W2E/RC_THOUSAND_SEP_ERR
The string contains a thousand separator after the decimal separator.
WEX0168 - W2E/RC_SIGN_ERROR
A negative sign has been found in a position that is not the first in the string.
WEX0169 - W2E/RC_DECIMAL_ERR
The error indicates that even though the validation of the string has been successful, the move of the string value to a numeric field has resulted in an error. This error should never be returned.
WEX0170 - W2E/RC_LARGE_NUMBER
The string contains a valid number, but the value of the number is to large ( greater than the value that can be containe in a decimal 29.5 field).
WEX0171 - W2E/RC_NO_DECIMAL_SEP
The number has digits after the decimal point, but no decimal separator has been specified.
Solution: Either specify a decimal separator in the parameter - or if you specify the "Use Dataareas" option, set a value for the decimal separator in the WSYDDECSEP dataarea found in the database library of Websydian Express.
WEX0172 - W2E/RC_NO_THOUSAND_SEP
The parameters specify that a decimal separator should be taken from a data area and the number is large enough for a decimal separator to be needed - but no decimal separator is specified in the data area.
Solution: Specify a value for the thousand separator in the WSYDTHUSEP data area found in the database library.
WEX0173 - W2E/RC_INVALID_DATE
The specified date was invalid.
WEX0174 - W2E/RC_INVALID_DATEMASK
The specified datemask was invalid.
WEX0180 - W2E/RC_INVALID_SITE
An invalid site has been specified.
WEX0181 - W2E/RC_NO_ANONYMOUS_USER
An API, which needs information about the anonymous user for a site has been called - however, no anonymous user could be found for the site.
WEX0182 - W2E/RC_INVALID_USER
An invalid user has been specified.
WEX0183 - W2E/RC_INVALID_FOLDERLIST
An invalid folder list has been specified.
WEX0185 - W2E/RC_INVALID_ROLE
An invalid role has been specified.
WEX0186 - W2E/RC_USEREXISTONSESSION
A user has already been specified for the session. The user can't be changed for an existing session.