API Reference Documentation

• Overview
• Core APIs
  • GetInput
  • SetOutput
  • SetGridOutput
  • SetParm
  • SetGridParm
  • GetParm
  • ValidateParm
  • WriteLog
  • WritePage
  • GetEventID
  • WriteErrorPage
  • ReloadSitePage
  • GetProcessParm
• Folder List APIs
  • FldrLGet
  • FldrLGetID
  • FldrLGetFirst
  • FldrLGetNext
• Session APIs
  • GetSessionID
  • GetSessionData
  • SessionGetAuth
  • SessionCreate
  • SessionUpdate
  • SessionGet
  • SessionAddRole
  • SessionIsAuthRole
  • SessionGetRoleFirst
  • SessionGetRoleNext
  • SessionRmvRole
  • SessionRmvAllRoles
  • SessionSetAnonymous
  • SessionSetUser
  • SessionSetFlrLst
  • SessionRefreshFlrLst
• Site APIs
  • SiteGet
• User APIs
  • UserCreate
  • UserDelete
  • UserGet
  • UserUpdate
  • UserGetID
  • UserUpdatePwd
  • UserCheckPwd
  • UserChgStatus
  • UserGetFirst
  • UserGetNext
  • UserAddRole
  • UserIsAuthRole
  • UserRmvRole
  • UserRmvAllRoles
  • UserGetRoleFirst
  • UserGetRoleNext
  • UserIncrFailed
  • UserRestFailed
• Role APIs
  • RoleGet
  • RoleGetByName
  • RoleCreate
  • RoleDelete
  • RoleSetIntranet
  • RoleClearIntranet
  • IsRoleInIntranet
  • RoleUpdate
  • RoleGetFirst
  • RoleGetNext
• Custom Field APIs
  • CustomFldValueGet
  • CustomFldValueSet
  • CustomFldGetFirstVal
  • CustomFldGetNextVal
  • CustomFldGetFirstInst
  • CustomFldGetNextInst
• Presentation APIs
  • GetCurrentPresentation
  • GetPresentation
  • SetPresentationProperty
  • GetPresentationProperty
  • DeletePresentationProperty
  • GetFirstProperty
  • GetNextProperty
• Authorization Level APIs (Deprecated)
• Return Codes

Overview

The APIs described in this section are the core of the Websydian Express RPGDeveloper.

All of these API's are prototyped in header files which can be imported into programs either separately or by including the EXPRESS_H header file, which includes all of the header files mentioned below.

The header files are delivered as members in the QRPGLESRC source file that is placed in the Websydian Express runtime library (default WXPnnPGM).

The APIs makes it possible to receive and handle requests from browsers and generate web pages which can then be sent as reply to the browser.

In addition to this, access to basic Websydian Express data are made possible by a set of APIs.

The interface of the APIs are specified by the header files. Examples of how to use the most important APIs can be found in the delivered examples.

The main goal of this document is to give a short description of the idea behind each API - and to describe any special behavior the API might have.

Core APIs

Header file: WICORE_H

These are the main APIs used to either handle requests from the browser or generate web pages.

GetInput

When a request is received from a browser, the request will very often contain input data. These data will often originate from input fields where the user can enter data (e.g. specify the quantity for an item he wants to order - enter an address for a registration event). These data are sent as a combination of the name of the value, and the value itself.

The GetInput parameter is called with the name of the value to fetch as an input parameter, and the value is returned as an output parameter.

SetOutput

The SetOutput API is used to assign a value to a replacement marker in a specific template. When the WritePage API later is called for the template, the value will be used to replace the replacement marker (if the replacement marker is found in the template).

If the SetOutput function is called more than once for a combination of template and name, the value specified on the last call will be used for the replacement.

The API have an "nopass" parameter HtmlCharEsc. This controls whether a number of special characters (<, >, ", &, #) is replaced with character expressions before being shown on the generated HTMLPage.

Unless DISABLE (False) is specified for the parameter, the conversion will take place.

SetGridOutput

The SetGridOutput API is used to assign a value to a replacement marker in a specific row in a specific template. When the WritePage API later is called for the template, the value will be used to replace the replacement marker in the specified row of the grid (if the replacement marker is found in the template).

If the SetGridOutput function is called more than once for a combination of template, gridrow, and name, the value specified on the last call will be used for the replacement.

The API have an "nopass" parameter HtmlCharEsc. This controls whether a number of special characters (<, >, ", &, #) is replaced with character expressions before being shown on the generated HTMLPage.

Unless DISABLE (False) is specified for the parameter, the conversion will take place.

SetParm

When generating a web page, it is also necessary to generate each event the user should be able to execute on the page (buttons, links). In some cases the program generating the page has got access to some information it needs to transfer to the program handling the event. This information can be added to the event by calling the SetParm API.

If the SetParm function is called more than once for a combination of template, event, and name, the value specified on the last call will be added to the event.

SetGridParm

When generating a web page, it is also necessary to generate each event the user must be able to execute on the page (buttons, links). In some cases the program generating the page has got access to some information it needs to transfer to the program handling the event.

When the event is placed in a grid this information can be added to the event by calling the SetGridParm API.

If the SetParm function is called more than once for a combination of template, gridrow, event, and name, the value specified on the last call will be added to the event.

GetParm

This is the function used by the function handling the event to retrieve the values which has been added to the event by the SetParm/SetGridParm APIs.

ValidateParm

One of the issues with making internet based solutions is that the users (and even other persons) are able to tamper with the data sent from the browser to the program handling the requests.

This means that even though the parameters added to the request by using the SetParm/SetGridParm functions can't be seen in the browser, they can in fact be changed by the user.

The ValidateParm function makes it possible for the program handling the request to discover if this has happened. Just call the ValidateParm function after having fetched the values of the parameters using the GetParm function - the ValidateParm function will return an error if the values are not as expected.

WriteLog

Calling this function writes a message to the Websydian Express message log. You can specify the severity of the message by specifying a category for the message.

The function can be used if you want to send information from the program to an administrator or want to obtain diagnostic information about the program without showing the information to the user.

The message log can be accessed through the Websydian Express administration interface.

WritePage

This API generates a HTML page based on a template and values set using the SetOutput, SetGridOutput, SetParm, and SetGridParm APIs.

After the page is generated, it is sent to the browser.

Called by the program handling a request. The API returns the identification of event being handled (which button/link has been pressed).

GetEventID

This API returns the EventID for the request being handled. This is used to identify the button/link which has been activated, which determines the further actions for the program handling the request.

WriteErrorPage

Calling this function generates an error page and sends it to the browser. The error page will show the message specified in the input.

After calling the WriteErrorPage API, the WritePage function  should not be called (as a page has already been sent to the browser).

ReloadSitePage

Callings this function reloads the site by generating an HTML page containing an event that reloads the site - this event is executed automatically, when the page is loaded.

When calling this function it is essential that template WSLOAD is present in a folder in the folder list specified for the session.

The result is that the browser window is reloaded with the site based on the user, roles, and folder list currently assigned to the session.

The ReloadSitePage inherits from PageGeneratorNoPresentation, this means that you do not have to make a special version of this page for each presentation.

After calling the ReloadSitePage API, the WritePage function  should not be called (as a page has already been sent to the browser).

GetProcessParm

This API retrieves the value specified for process parameters specified on a menu service link.

The API is called once for each parameter that can be specified as a parameter on a menu service.

The API retrieves the value of the parameter if the signature check ensuring the integrity of the parameters has been performed.

Folder List APIs

Header file: WIFOLDER_H

These APIs are used to retrieve information about the folder lists registered in the system.

FldrLGet

Retrieves information about a specific folder list from the Websydian Express database. The key used to read the data is the FolderListID.

FlderLGetID

Retrieves information about a specific folder list from the Websydian Express database. The key used to read the data is a combination of the SiteKey (unique identification of a site) and the name of the folder list.

FldrLGetFirst

Used when reading an ordered list of the folder lists defined in the Websydian Express installation. The list is ordered by the name of the folder list. Only folder lists for a specific site will be retrieved.

The FldrLGetFirst API is used to establish a position in the list - and to retrieve the first record after this position.

FldrLGetNext

Used to retrieve information about the next record in the list of folder lists. The FldrLGetFirst API must always be called before calling the FldrLGetNext API.

Session APIs

Header file: WISESS_H

These APIs are used to retrieve or update information about Websydian Express sessions.

GetSessionID

This API can be called by a program handling a request. It identifies and returns the identification of the session originating the request.

GetSessionData

Retrieve the information stored about a session in the Websydian Express database.

SessionGetAuth

Retrieves the authorization level for a session.

As an example, this API can be used if you want to show different information for different types of users, by calling this API before setting the output you can determine the type of user accessing the application.

SessionCreate

This is only relevant if a program outside the Websydian Express runtime need to create the session.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

SessionUpdate

This can be used if you want your application to update information on the session.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

SessionGet

Retrieve the information stored about a session in the Websydian Express database. Compared to the GetSessionData API, it retrieves a subset of the information.

SessionAddRole

Extends the authorization of a session by adding a role to the session. This makes it possible for the session to access all Site Elements authorized by the role.

SessionIsAuthRole

Checks whether the session is authorized by the specified role. Use this API if your business process contains information/processing the should only be available for sessions with the specified role.

SessionGetRoleFirst

Used together with the SessionGetRoleNext API to retrieve a list of the roles assigned to the session. The roles are retrieved in role name order. The API retrieves the first role of the list and sets the position for calls to SessionGetRoleNext. SessionGetRoleFirst must be called before calling SessionGetRoleNext.

SessionGetRoleNext

Used together with the SessionGetRoleFirst API to retrieve a list of the roles assigned to the session. The API retrieves the next role of the list. SessionGetRoleFirst must be called before calling SessionGetRoleNext.

SessionRmvRole

Removes a role from a session.

SessionRmvAllRoles

Removes all roles assigned to a session. This means that the session no longer will have access to any site elements.

SessionSetAnonymous

Set the roles and folder list based on the anonymous user specified on the site settings. This API can't be called if there is already a user assigned to the session.

SessionSetUser

Set the roles and folder list based on the specified user. This API can't be called if there is already a user assigned to the session.

SessionSetFlrLst

Specify a folder list for the session.

SessionRefreshFlrLst

Refresh the folder list for the session so that it corresponds to the roles and user currently assigned to the session.

Site APIs

Header file: WISITE_H

Use this API to retrieve information about Websydian Express Sites.

SiteGet

Retrieves information about a specific site.

User APIs

Header file: WIUSER_H

Use these APIs to retrieve and update information about Websydian Express Users.

UserCreate

Used to create a user profile in the Websydian Express database. An example of the use of this API can be seen in the User Self Registration example.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

UserDelete

Used to delete a user profile in the Websydian Express database.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

UserGet

Used to retrieve information about a user profile from the Websydian Express database.

UserUpdate

Used to update information about a user profile in the Websydian Express database.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

UserGetID

Used to identify the UserID from a combination of SiteKey and LoginName. The UserID can then be used to retrieve further information about the user using the UserGet API.

UserUpdatePwd

Used to update the password stored for a user profile.

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

UserCheckPwd

Used to check whether an entered password corresponds to the value stored in the database.

UserChgStatus

Changes the status of a user. An example of use of this API could be a function deactivating all users who have not logged into the application in a certain timeframe (or activating a number of predefined users, who should get access to a site).

Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.

UserGetFirst

Used when reading an ordered list of the user profiles defined in the Websydian Express installation. The list is ordered by the name of the login name of the users.

The UserGetFirst API is used to establish a position in the list - and to retrieve the first record after this position.

The API will always retrieve users for one specific site.

It is possible to limit the list to containing records with a specific authorization level, folder list, creating user, e-mail and/or status.

UserGetNext

Used to retrieve the next user in the list. The UserGetFirst API must be called before calling the UserGetNext is called.

UserAddRole

Used to extend the authorization of a user by adding a role to the user.

UserIsAuthRole

Checks whether a user is authorized for a role.

UserRmvRole

Removes a role from the user. This removes authorization from the user.

UserRmvAllRoles

Removes all roles from the user. This means that the user will no longer have access to any Websydian Express site elements. This API can be called if a user is to be deleted - as all roles must be removed from before the user can be deleted.

UserGetRoleFirst

Used together with UserGetRoleNext to retrieve a list of the roles assigned to the user. The roles are retrieved in role name order. This API retrieves the first record and sets the position for calls to UserGetRoleNext. UserGetRoleFirst must be called before calling UserGetRoleNext.

UserGetRoleNext

Used together with UserGetRoleFirst to retrieve a list of the roles assigned to the user. The roles are retrieved in role name order. This API retrieves the next role in the list. UserGetRoleFirst must be called before calling UserGetRoleNext.

UserIncrFailed

Adds 1 to the current number of failed logins registered for the user. Can be used by custom made login processes when a user has tried to log in using an invalid password.

Please note that this API does not set the user to inactive after a number of failed logins - this has to be done by call to the UserChgStatus API.

UserResetFailed

Resets the number of failed logins registered for a user to 0. Can be used by custom made login processes when a user has successfully logged in.

Role APIs

Header File: WIROLE_H

RoleGet

Retrieves information about the role specified by the RoleSurrogate (unique identification of the Role).

RoleGetByName

Retrieves information about the role specified by the name of the role - for a specific site.

RoleCreate

Creates a role (for a specified site) after validating the input parameters.

The API can be called in a validation mode where only the validation is performed.

RoleDelete

Deletes an existing role after validating whether the role can be deleted.

The API can be called in a validation mode where only the validation is performed.

RoleSetIntranet

Marks the role as being for intranet use only. Roles with this designation is not assigned to sessions originating outside the specified intranet mask (See Site Settings).

RoleClearIntranet

Removes the intranet limitation from a role. This means that site elements authorized with this roles will be available from outside the intranet.

IsRoleInIntranet

Checks whether the role is specified as being for intranet use only.

RoleUpdate

Updates the information for a role after validating the specified information.

The API can be called in a validation mode where only the validation is performed.

RoleGetFirst

Used together with RoleGetNext to retrieve a list of the roles for a specific site. The roles are retrieved in role name order. RoleGetFirst retrieves the first role in the list and sets the position for the RoleGetNext API.

RoleGetNext

Used together with RoleGetFirst to retrieve a list of the roles for a specific site. The API retrieves the next roles in the list.

Custom Fields APIs

Header File: WICUSTOM_H

These APIs can be used to retrieve or update information about the Websydian Express custom fields.

CustomFldValueGet

Retrieves the current value of the custom field for the specified record.

CustomFieldValueSet

Sets the value for the custom field for the specified record.

CustomFldGetFirstVal

Used together with the CustomFldGetNextVal API to retrieve a list of all custom fields and their values for the specified record. The custom fields are retrieved in custom field name order. The API retrieves the first record and sets the position for further reads using CustomFldGetNextVal. CustomFldGetFirstVal must always be called before calling CustomFldGetNextVal.

CustomFldGetNextVal

Used together with the CustomFldGetFirstVal API to retrieve a list of all custom fields and their values for the specified record. CustomFldGetFirstVal must always be called before calling CustomFldGetNextVal.

CustomFldGetFirstInst

Used together with CustomFldGetNextInst to retrieve a list of the record in a specific entity that has a specific value for a custom field. The records are retrieved in instance key order. CustomFldGetFirstInst must always be called before calling CustomFldGetNextInst.

CustomFldGetNextInst

Used together with CustomFldGetFirstInst to retrieve a list of the record in a specific entity that has a specific value for a custom field. CustomFldGetFirstInst must always be called before calling CustomFldGetNextInst.

Presentation APIs

Header File: WIPRES_H

These APIs can be used to retrieve information about presentations and to work with the properties that has been specified for the presentations.

GetCurrentPresentation

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. Apart from retrieving this information, you can use the returned presentation surrogate to retrieve or set properties for the presentation using the SetPresentationProperty, GetPresentationPropety, DeletePresentationProperty, GetFirstProperty, and GetNextProperty APIs.

GetPresentation

This API can be used to retrieve data from a presentation and the process it belongs to based on the presentation surrogate (unique identification) of the presentation.

SetPresentationProperty

Records a value for a property for a specific presentation. If the property already has a value assigned this value is changed, if the property does not exist, it is created with the specified value.

In many cases you will want to set a property for the current presentation. You can retrieve the identification of this presentation by calling the GetCurrentPresentation API.

GetPresentationProperty

Retrieves the value specified for a property for a specific presentation. If the property has not been created, RC_NOT_FOUND is returned by the function. If the property has been created without a value, blank is returned for the value, while RC_SUCCESS is returned by the function.

In many cases you will want to get a property for the current presentation. You can retrieve the identification of this presentation by calling the GetCurrentPresentation API.

DeletePresentationProperty

Deletes the specified property for the specified presentation.

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.

GetFirstProperty

This API is used together with GetNextProperty to retrieve a list of all properties specified for a specific presentation. The properties are retrieved in property name order.

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 PosPropName.

GetNextProperty

This API is used together with GetFirstProperty to retrieve a list of all properties specified for a specific presentation. The properties are retrieved in property name order.

You must call GetFirstProperty for the presentation before calling GetNextProperty, as GetFirstProperty establishes the starting point for the list of data to retrieve.

 

Authorization Level APIs

As the authorization levels has been replaced by role based authorization, these APIs are all deprecated.

Return Codes

These are the return codes, which can be returned by the APIs described above.

RC_SUCCESS (0)

Returned if the processing has been successful.

RC_NOT_FOUND (1)

Returned by APIs retrieving data if no record could be found based on the entered selection criteria.

RC_UNKNOWN (-1)

Returned when an unexpected error has occurred in a low level function.

Example: An object is missing from the runtime library.

RC_NO_FLD_NME (-2)

Returned if an API, having a mandatory input parameter specifying a field name, has been called with a blank name.

RC_INVALID_SES (-6)

Returned if an invalid session id (typically 0/blank) has been specified as input or retrieved from a request.

RC_NO_KEY (-7)

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. Please check the site settings for the current site in the administration interface.

RC_NO_TEMPLATE (-9)

Returned if an API, having a mandatory input parameter specifying a template, id has been called with a blank id.

RC_INVALID_SGN (-13)

The function validating the parameters retrieved from the request has found that the values of the parameters is not correct.

RC_NO_GRIDROW (-14)

Returned if an API, having a mandatory input parameter specifying a row in a grid, has been called with a row number lower than one.

RC_NO_EVENTID (-15)

Returned if an API, having a mandatory input parameter specifying an event id has been called with a a blank id.

RC_MANY_TEMPL (-16)

There is a limit to the number of include pages containing grids that can be contained in one page (at the moment 100). If this limit is exceeded, this code is returned.

If this happens, consider whether there really is a need for this number of included grids on your page.

If absolutely necessary contact Websydian Support to obtain a version handling a larger number of included grids.

RC_SES_READ_ER (-20)

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.

RC_CRT_FAILED (-21)

Returned when an API creating new records in the Websydian Express database has encountered an error meaning that the record could not be created.

RC_UPD_FAILED (-22)

Returned when an API updating records in the Websydian Express database has encountered an error meaning that the record could not be updated.

RC_VAL_FAILED (-23)

Returned when an API has been called in the validation mode (ValidateOnly = VALIIDATE) - and the validation has registered one or more errors.

RC_DLT_FAILED (-24)

Returned when an API deleting records in the Websydian Express database has encountered an error meaning that the record could not be deleted.

RC_READ_FAILED (-25)

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).

RC_PWD_FAILED (-26)

Returned by the UserCheckPwd function if the entered password does not correspond to the one registered for the user.

RC_GETNEXT_ERR (-29)

A GetNext function has been called without any calls being made to the corresponding GetFirst function.

RC_CAT_INVALID (-30)

An invalid category has been specified for a call to the WriteLog API.

RC_NO_MESSAGE (-31)

The WriteLog API has been called without any message being specified.

RC_CALL_FAILED (-32)

A call to a program/serviceprogram has failed (typically as a PSDS error). More information can typically be found in the Websydian Express message log and the OS400 joblog.

RC_INVALID_PWD (-33)

A function updating the password for a user have been called with an invalid value (typically blank) for the password.

RC_DTAARA_READ (-34)

The service functions used to format numeric or date fields could not read a necessary dataarea - check the library list for the job.

RC_SAME_SEPARA (-35)

The same separator character has been specified for the thousand separator and the decimal separator.

RC_TWO_DECIMAL (-36)

The string contains more than one decimal separators.

RC_INVALID_NBR (-37)

The string contains invalid (non-numeric) characters.

RC_THOUSEP_ERR (-38)

The string contains a thousand separator after the decimal separator.

RC_SIGN_ERR (-39)

A negative sign has been found in a position that is not the first in the string.

RC_DECIMAL_ERR (-40)

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.

RC_LARGE_NBR (-41)

The string contains a valid number, but the value of the number is to large ( > 29.5).

RC_NO_DECSEP (-42)

The number has digits after the decimal point, but no decimal separator has been specified.

RC_NO_THOUSEP (-43)

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.

RC_INVALID_DAT (-44)

The specified date was invalid.

RC_DATEMSK_ERR (-45)

The specified datemask was invalid.

RC_INV_SITE (-46)

An invalid site has been specified.

RC_NO_ANONYM (-47)

No anonymous user has been specified for the site.

RC_INV_USER (-48)

An invalid user has been specified.

RC_INV_FOLDERL (-49)

An invalid folder list has been specified.

RC_INV_ROLE (-50)

An invalid role has been specified.

RC_USER_EXIST (-51)

A user has already been specified for the session. The user can't be changed for an existing session.