USYSHTTP

The USYSHTTP component is a global web application request processor that handles all web requests sent to a Uniface Server via the Uniface Web Request Dispatcher (WRD).

The USYSHTTP component parses the information sent by the web client and populates the appropriate $webinfo input channels. It then activates the requested instance and operation or trigger, and returns a response.

A web request is mainly handled by the code inside the WRDEXEC operation, which is directly activated by the WRD. The component name USYSHTTP and the operation name WRDEXEC are hardcoded and cannot be changed.

The way a web request is handled typically varies per component type. To handle this, there are three request handlers:

  • ent:DSP.HANDLER—Handles Dynamic Server Page (DSP) requests
  • ent:USP.HANDLER—Handles Static Server Page (USP) requests
  • ent:SVC.HANDLER—Handles other HTTP requests, like REST

The USYSHTTP component is accompanied with the USYSHTTP Global ProcScript Library. The modules in this library provide helper functions for the USYSHTTP component including functions specific to the DSP protocol. These cannot be edited or debugged.

Modifying USYSHTTP

You can modify the USYSHTTP component to change the behavior of how web requests are handled.

The following diagram shows the flow of the USYSHTTP component, and the resulting flow if it executes successfully and when an error occurs. Operations in the white boxes can be customized. Operations in the blue boxes call the USYSHTTP Global ProcScript library functions.

USYSHTTP component flow

An overview of the USYSHTTP component

You can add your own logic and custom handlers to the functions indicated below.

Customizable USYSHTTP operations
Operation Description
vRequestHandler=getHandler() Gets the request handler based on the component type of the requested component. You can modify this to add your own way to identify the request handler.
vRequestHandler->getRequest()

Gets the request from the specific request handler for your component type. The getRequest function cannot be customized, but you may use your own custom handlers.
newinstance/attached pComponentName, pInstanceName

Instantiates the requested component instance.

vActivateStatus = vRequestHandler->activateRequest()

Activates the requested operation or trigger. Add your own logic as required.
vRequestHandler->genResponse()

Generates a response from the specific handler for your component type.
catch{vRequestHandler->reportError()}

Reports uncaught exceptions. While you cannot edit the handler or reportError function, you can add your own error reporting here.
rollback Performs a rollback to make sure there are no open transactions.
deleteinstance vInstanceName

Deletes all attached instances explicitly to allow any thrown exceptions from the cleanup triggers to be reported by the Uniface Server application shell.

Note: Detached instances or global variables are not deleted. If you require this, explicitly add code here to do so.

Note: We do not advise editing or deleting request handlers or calls to functions that are not marked as optional in the code. However, you can point these to your own custom handlers or functions.

To inspect or modify the USYSHTTP component, import it from the uniface/misc folder. Detailed development documentation is included in the code as comments.

USYSHTTP Global ProcScripts

The following protocols and helper functions are called by the USYSHTTP component. While these cannot be edited, you can change the USYSHTTP component to point to your own custom handlers or functions.

USYSHTTP Global ProcScripts
Operation Description
usyshttp::getRequest()1

Fetches the request from the Uniface Web Request Dispatcher (WRD) and parses it.

usyshttp::dspgetRequest()1

Gets the request from the DSP request handler. The getRequest function cannot be customized, but you may use your own custom handlers.
usyshttp::callPreRequest()2

Calls the application shell's preRequest trigger (APS: preRequest).
usyshttp::callPostRequest()2

Calls the application shell's postRequest trigger (APS:postrequest).
usyshttp::dspGenResponse(OPERRESPONSE)1

Generates a response based specifically on a DSP component.
usyshttp::getReturnValue()

Gets ReturnValue item from $procerrorcontext when an exception is caused by the negative return value.
usyshttp::getException(PROCERRORCONTEXT)

Gets the exception from the provided ProcScript error context.

usyshttp::reportError()

Generates an error report as an HTML document to $webinfo("OUTPUT"). If you're using classic error handling, this is the classic yellow page error report.

You can write your own error reporting.
usyshttp::genResponse()1

Puts the generated response in the $webinfo("output") channel. This response is sent back to the client.
usyshttp::clearWebinfo() Clears all $webinfo topics before and after processing the web request.

Notes:

  1. These functions are Uniface protocols that must be called by the USYSHTTP component, and we do not advise replacing them. You can wrap these operations with additional code.
  2. These functions are optional. You can remove them and add your own functions.

Trigger Activation Sequence for Web Requests

In web applications, the USYSHTTP component handles web requests from the WRD and executes a sequence of triggers and operations. Subsequent behavior depends on whether these triggers are enabled to throw exceptions.

Triggers are Exception-Enabled

When the trigger is enabled to throw exceptions:

  • The USYSHTTP component always returns 0 in $status, regardless of whether an exception is thrown.
  • If an exception occurs, the WRD displays a yellow page containing the context information from $procerrorcontext.

The following table show the trigger activation sequence of a web request from left to right. The first row shows the successful activation sequence, with no exceptions thrown.

Activation Sequence for Exception-Enabled Triggers
preRequest preActivate operation/trigger postActivate postRequest Result
return >= 0 return >= 0 return >= 0 Executed Executed Successful response
throws < 0 Not executed Not executed Not executed Not executed Exception with $procerror < 0
return >= 0 throws < 0 Not executed Not executed Not executed Exception with $procerror < 0
return >= 0 return >= 0 throws < 0 Not executed Not executed Exception with $procerror < 0
return >= 0 return >= 0 return >= 0 throws < 0 Not executed Exception with $procerror < 0
return >= 0 return >= 0 return >= 0 Executed throws < 0 Exception with $procerror < 0

Triggers Cannot Throw Exceptions

If the trigger cannot throw exceptions (classic error handling):

  • The USYSHTTP component returns the value in $status.
  • If an error occurs, the WRD displays a yellow page containing the context information from $procerrorcontext.

    However, for $status = -21, it displays a red page with HTTP code 401.

The first row shows the successful activation sequence, with no errors reflected in $status.

Activation Sequence without Exceptions
preRequest preActivate operation/trigger postActivate postRequest

Result
return >= 0 return >= 0 return >= 0 Executed Executed Successful response
return = -21 Not executed Not executed Not executed Not executed Authorization failure
return < 0 Not executed Not executed Not executed Not executed Exception with $procerror < 0
return >= 0 return =-21 Not executed Not executed Executed Authorization failure
return >= 0 return < 0 Not executed Not executed Executed Exception with $procerror -71
return >= 0 return >= 0 return < 0 Executed Executed Exception with $procerror < 0

For more information, see Runtime Error Handling in ProcScript.

Related Topics