|
|
The APIs described in this section are the core of the WebsydianExpress 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 WebsydianExpress 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 WebsydianExpress 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.
Please note that the interface is defined in the header file - some further information/comments for each API can also be found in the header files.
Header file: WICORE_H
These are the main APIs used to either handle requests from the browser or generate web pages.
It is important to be aware of the fact that all values are handled as character strings.
This means that if you have e.g. a numeric field and want to write the field to a page, you must always first convert this field to a character string (relevant for the SetOutput, SetGridOutput, SetParm, and SetGridParm APIs).
If you receive a non character field from a request, you must convert this from the character representation to the suitable non-character representation before handling the field. To ensure the reliability of the program you should check that the received value corresponds to the expected type (e.g. a numeric field only contains numbers etc.) before converting the value. (relevant for the GetInput and GetParm APIs).
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.
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.
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.
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.
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.
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.
It is important that the GetParm function is called once for each parameter set by SetParm/SetGridParm.
After calling the GetParm function for each parameter, the ValidateParm function must be called to ensure the integrity of the data.
There is no GetGridParm API. Use the GetParm API no matter whether the parameter has been set using the SetParm or the SetGridParm API.
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.
Calling this function writes a message to the WebsydianExpress 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 WebsydianExpress administration interface.
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.
For each request, only one call to the WritePage API should be made.
Called by the program handling a request. The API returns the identification of event being handled (which button/link has been pressed).
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.
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).
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).
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.
Header file: WIFOLDER_H
These APIs are used to retrieve information about the folder lists registered in the system.
Retrieves information about a specific folder list from the WebsydianExpress database. The key used to read the data is the FolderListID.
Retrieves information about a specific folder list from the WebsydianExpress 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.
Used when reading an ordered list of the folder lists defined in the WebsydianExpress 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.
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.
Header file: WISESS_H
These APIs are used to retrieve or update information about WebsydianExpress sessions.
This API can be called by a program handling a request. It identifies and returns the identification of the session originating the request.
Retrieve the information stored about a session in the WebsydianExpress database.
This is only relevant if a program outside the WebsydianExpress 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.
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.
Retrieve the information stored about a session in the WebsydianExpress database. Compared to the GetSessionData API, it retrieves a subset of the information.
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.
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.
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.
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.
Retrieves the current language for a session.
Updates the current language for a session.
Removes a role from a session.
Removes all roles assigned to a session. This means that the session no longer will have access to any site elements.
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.
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.
Specify a folder list for the session.
Refresh the folder list for the session so that it corresponds to the roles and user currently assigned to the session.
Retreives the session id for the current session.
Header file: WISITE_H
Use this API to retrieve information about WebsydianExpress Sites.
Retrieves information about a specific site.
Retrieve the first site that is defined for the installation. The list of sites is returned in site description order.
Retrieve the next site that is defined for the installation. The list of sites is returned in site description order.
Header file: WIUSER_H
Use these APIs to retrieve and update information about WebsydianExpress Users.
Used to create a user profile in the WebsydianExpress 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.
Used to delete a user profile in the WebsydianExpress database.
Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.
Used to retrieve information about a user profile from the WebsydianExpress database.
Used to update information about a user profile in the WebsydianExpress database.
Calling the API with the parameter ValidateOnly = VALIDATE means that the API will not update the database - only the validation will be performed.
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.
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.
Used to check whether an entered password corresponds to the value stored in the database.
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.
Used when reading an ordered list of the user profiles defined in the WebsydianExpress 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.
Used to retrieve the next user in the list. The UserGetFirst API must be called before calling the UserGetNext is called.
Used to extend the authorization of a user by adding a role to the user.
Checks whether a user is authorized for a role.
Removes a role from the user. This removes authorization from the user.
Removes all roles from the user. This means that the user will no longer have access to any WebsydianExpress 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.
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.
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.
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.
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.
Specifies the default language for the user.
Retrieves the default language for the user.
Header File: WIROLE_H
Retrieves information about the role specified by the RoleSurrogate (unique identification of the Role).
Retrieves information about the role specified by the name of the role - for a specific site.
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.
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.
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).
Removes the intranet limitation from a role. This means that site elements authorized with this roles will be available from outside the intranet.
Checks whether the role is specified as being for intranet use only.
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.
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.
Used together with RoleGetFirst to retrieve a list of the roles for a specific site. The API retrieves the next roles in the list.
Header File: WICUSTOM_H
These APIs can be used to retrieve or update information about the WebsydianExpress custom fields.
Retrieves the current value of the custom field for the specified record.
Sets the value for the custom field for the specified record.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Header File: WICALB_H
These APIs can be used to retrieve and update information about callback points and the callback functions assigned to the callback points.
Creates a Callback Point for which you can afterwards specify a sequence of callback functions to call.
Deletes a Callback Point and all of the functions assigned to it.
Update information about a specific callback point.
Retrieve information about a specific callback point
Adds a function to the specified Callback point
Removes the specified callback function from the callback point.
Updates information for a callback function
Retrieves information about the first function in a list. Together with CallbackFunctionGetNext, this can be used to list all the function specified for a callback point.
Retrieves information about the next record in a list. Together with CallbackFunctionGetFirst, this can be used to list all the function specified for a callback point.
Retrieves a callback parameter. This function is used in the callback functions to retrieve input parameter values set by the callback point.
When calling the API, you must specify a name for the field you want to retrieve the value for. In the header file CALLBACK_H, constants are defined for the fields used by the system defined callback point.
Sets a callback input parameter value. This can be used to implement a callback point that uses the same parameter transfer method as the system defined callback points.
When calling the API, you must specify a name for the field you want to set the value for. In the header file CALLBACK_H, constants are defined for the fields used by the system defined callback point.
Retrieves a value for a callback output parameter.
This can be used to implement a callback point that uses the same parameter transfer method as the system defined callback points.
When calling the API, you must specify a name for the field you want to retrieve the value for. In the header file CALLBACK_H, constants are defined for the fields used by the system defined callback point.
Sets an output parameter for a callback function. Call this function for each parameter you want to return from a callback function.
When calling the API, you must specify a name for the field you want to set the value for. In the header file CALLBACK_H, constants are defined for the fields used by the system defined callback point.
Header File: WILANG_H
These APIs can be used to retrieve and update information about languages. Please note that languages belongs to a site - so to update or retrieve the information about a language, you must specify both the language code and the sitekey.
Creates a language for a specific site. After this is done, you can assign this language to users and/or sessions and create language dependent texts for this language in translated entities.
Deletes the specified language for the specified site.
Retrieves information about a language for a specific site. You can specify which language translation you want the texts to be returned in by specifying a value for the parameter RetrieveLang.
Together with LanguageGetNext, you can use this function to retrieve a list of languages specified for a site. This function retrieves the first record, and sets the position for the following calls of LanguageGetNext. You must specify the Site for which you want to retrieve the languages. You can position the start of the list by specifying the language code you want to start the list with.
Together with LanguageGetFirst, you can use this function to retrieve a list of languages specified for a site. This function retrieves the next record in the list. You must always call LanguageGetFirst before calling this function to set the position in the list.
Update the information about a language.
This API can be used to translate the texts for a language.
Header File: WIAUEV_H
These APIs can be used to create, update, and delete authorized events. They can also be used to retrieve information about the events and their roles and they can be used to verify whether a specific session is authorized for a specific event.
Create an authorized event for a specific site.
You must specify a unique identification of the event for the AuthEventName. This name must be the same as the one you use when calling the AuthEventIsSessionAuth API in the EventHandler - and it is also the [eventname] used in the /(%IFAUTHEVENT-[eventname]) replacement marker.
You control the access to the event by specifying either "A", "R", or "N" for the field "AvailableFor".
A: All Users - everyone have access to the event
R: The access to the event is determined by inspecting the roles assigned to the event and to the session. If there is at least one common role, the session has access to the event.
N: No users have access to the event.
If you specify VALIDATE for ValidateOnly, the function will only perform the validation - the event will not be created.
Specify UPDATE to create (and validate) the event.
Delete the authorized event. The event record and all the relations between the event and the assigned roles are removed from the database.
Note that if you have deleted the record and WebsydianExpress finds a /(%IFAUTHEVENT-[eventname]) - or the AuthEventIsSessionAuth API is called for the event, a new authorized event record will be automatically created based on the default event for the site. This means that if you want to block all users from having access to the event, you should instead set the "AvailableFor" field to "N" (No users).
Update the information for the authorized event.
If you specify VALIDATE for ValidateOnly, the function will only perform the validation - the event will not be updated.
Specify UPDATE to update (and validate) the event.
Retrieve the authorized event based on the unique identification of the authorized event (AuthEventSgt).
Retrieve the first authorized event for the site. You must always specify a sitekey (unique identification of the site).
Use this together with AuthEventGetNext to retrieve a list of all the authorized events for the site.
Retrieve the next authorized event in the list defined by a previous call to AuthEventGetFirst (AuthEventGetFirst must be called before AuthEventGetNext).
Use this together with AuthEventGetFirst to retrieve a list of all the authorized events for the site.
Assign a role to the authorized event. If the authorized event has the value "R" (Rolebased) for "AvailableFor", adding a role means that sessions that has this role assigned will have access to the event.
You must specify the unique identifications for the authorized event and the role. If you only have the names, you can used the APIs AuthEventGetByName and RoleGetByName to find the unique identifications.
This function returns the default authorized event for the site. This event has the name *DEFAULT. The event is used as a template when the authorized events are created automatically.
If no default event is specified for the site, the API will create one - and return the information about this event.
Retrieve the information about an authorized event. Specify the site and the name of the authorized event to identify the event to retrieve.
Retrieve the first role that is assigned to the authorized event.
Use this API together with AuthEventGetNextRole to retrieve a list of all the roles assigned to a specific authorized event.
If you want to do this to check the authorization of a session, it is recommended to use the AuthEventIsSessionAuth API instead.
You must specify the AuthEventSgt (unique identification of the authorized event) to identify the authorized event you want to retrieve the roles for. If you do not know this, you can use the API AuthEventGetByName to retrieve the unique identification.
Retrieve the next role in the list defined by a prior call to AuthEventGetFirstRole. You must always call AuthEventGetFirstRole before calling AuthEventGetNextRole.
Use this API together with AuthEventGetFirstRole to retrieve a list of all the roles assigned to a specific authorized event.
This API should be used in your EventHandler when you want to check whether the session is authorized for the event.
The API will check whether an authorized event record exist for the specified AuthEventName. If no such record exist, a record will be created based on the default event for the current site.
You must specify the SessionID as input. The ID of the current session can be found by calling GetSessionID API.
This API removes the specified role from the specified authorized event.
This API removes all roles from the specified authorized event.
As the authorization levels has been replaced by role based authorization, these APIs are all deprecated.
These are the return codes, which can be returned by the APIs described above.
Returned if the processing has been successful.
Returned by APIs retrieving data if no record could be found based on the entered selection criteria.
Returned when an unexpected error has occurred in a low level function.
Example: An object is missing from the runtime library.
Returned if an API, having a mandatory input parameter specifying a field name, has been called with a blank name.
Returned if an invalid session id (typically 0/blank) has been specified as input or retrieved from a request.
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.
Returned if an API, having a mandatory input parameter specifying a template, id has been called with a blank id.
The function validating the parameters retrieved from the request has found that the values of the parameters is not correct.
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.
Returned if an API, having a mandatory input parameter specifying an event id has been called with a a blank id.
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.
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.
Returned when an API creating new records in the WebsydianExpress database has encountered an error meaning that the record could not be created.
Returned when an API updating records in the WebsydianExpress database has encountered an error meaning that the record could not be updated.
Returned when an API has been called in the validation mode (ValidateOnly = VALIIDATE) - and the validation has registered one or more errors.
Returned when an API deleting records in the WebsydianExpress database has encountered an error meaning that the record could not be deleted.
Returned when a function reading data from the WebsydianExpress 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).
Returned by the UserCheckPwd function if the entered password does not correspond to the one registered for the user.
A GetNext function has been called without any calls being made to the corresponding GetFirst function.
An invalid category has been specified for a call to the WriteLog API.
The WriteLog API has been called without any message being specified.
A call to a program/serviceprogram has failed (typically as a PSDS error). More information can typically be found in the WebsydianExpress message log and the OS400 joblog.
A function updating the password for a user have been called with an invalid value (typically blank) for the password.
The service functions used to format numeric or date fields could not read a necessary dataarea - check the library list for the job.
The same separator character has been specified for the thousand separator and the decimal separator.
The string contains more than one decimal separators.
The string contains invalid (non-numeric) characters.
The string contains a thousand separator after the decimal separator.
A negative sign has been found in a position that is not the first in the string.
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.
The string contains a valid number, but the value of the number is to large ( > 29.5).
The number has digits after the decimal point, but no decimal separator has been specified.
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.
The specified date was invalid.
The specified datemask was invalid.
An invalid site has been specified.
No anonymous user has been specified for the site.
An invalid user has been specified.
An invalid folder list has been specified.
An invalid role has been specified.
A user has already been specified for the session. The user can't be changed for an existing session.
Online documentation - WebsydianExpress v3.5