PageHandler part properties

Excluding properties that are specific to PageHandler fields, the properties of the PageHandler are as follows and are optional:
alias = "alias"
A string that is incorporated into the names of generated output. If you do not specify an alias, the PageHandler part name is used instead.
allowUnqualifiedItemReferences = no, allowUnqualifiedItemReferences = yes
Specifies whether to allow your code to reference structure items but to exclude the name of the container, which is the data table, record, or form that holds the structure item. Consider the following record part, for example:
  Record aRecordPart type basicRecord
    10 myItem01 CHAR(5);
    10 myItem02 CHAR(5);
  end
The following variable is based on that part:
  myRecord aRecordPart;
If you accept the default value of allowUnqualifiedItemReferences (no), you must specify the record name when referring to myItem01, as in this assignment:
  myValue = myRecord.myItem01;
If you set the property allowUnqualifiedItemReferences to yes, however, you can avoid specifying the record name:
  myValue = myItem01;

It is recommended that you accept the default value, which promotes a best practice. By specifying the container name, you reduces ambiguity for people who read your code and for EGL.

EGL uses a set of rules to determine the area of memory to which a variable name or item name refers. For details, see References to variables and constants.

cancelOnPageTransition = yes, cancelOnPageTransition = no
This property determines whether the page bean is removed from the session scope when the user's browser loads a new page. Page beans are the Java components that represent the logic behind the page on the Web server. If you set the property to YES, (the default) EGL behaves as it does normally, that is, the bean is removed from session scope when another page bean is instantiated. If you set the property to NO, the bean is not removed and remains in scope when the user loads a new page.
handleHardIOErrors = yes, handleHardIOErrors = no
Sets the default value for the system variable VGVar.handleHardIOErrors. The variable controls whether a program continues to run after a hard error has occurred on an I/O operation in a try block. The default value for the property is yes, which sets the variable to 1.

For other details, see VGVar.handleHardIOErrors and Exception handling.

includeReferencedFunctions = no, includeReferencedFunctions = yes
Indicates whether the PageHandler bean contains a copy of each function that is neither inside the PageHandler nor in a library accessed by the PageHandler. The default value is no, which means that you can ignore this property if you are fulfilling the following practices at development time, as is recommended:
  • Place shared functions in a library
  • Place non-shared functions in the PageHandler

If you are using shared functions that are not in a library, generation is possible only if you set the property includeReferencedFunctions to yes.

localSQLScope = no, localSQLScope = yes
Indicates whether identifiers for SQL result sets and prepared statements are local to the pageHandler, as is the default. If you accept the value yes, different programs that are called from the pageHandler can use the same identifiers independently.

If you specify no, the identifiers are shared throughout the run unit. The identifiers created in the current code are available elsewhere, although other code can use localSQLScope = yes to block access to those identifiers. Also, the current code may reference identifiers created elsewhere, but only if the other code was already run and did not block access.

The effects of sharing SQL identifiers are as follows:
  • You can open a result set in a pageHandler or called program and get rows from that set in the other code
  • You can prepare an SQL statement in one code and run that statement in another
msgResource = "fileName"
Identifies a Java™ resource bundle or properties file that is used in error-message presentation. The Java runtime searches for the file, which must be in a directory listed in the Java classpath.

The search is for a file whose name begins with fileName, with an environment-specific locale value appended to that name. The Norwegian version of a resource bundle called myFile, for example, is myFile_no.

First, the runtime search is for a file with extension class (for a resource bundle); but if that file is not found, the search is for a file with extension properties (for a properties file).

The content of the resource bundle or properties file is composed of a set of keys and related values. A particular value is displayed in response to the program's invoking the EGL system function sysLib.setError, when the invocation includes use of the key for that value.

onPageLoadFunction = "functionName"
The name of a PageHandler function that receives control when the related JSP initially displays a Web page. This function can be used to set up initial values of the data displayed in the page. This property was formerly the onPageLoad property.

Arguments passed to the function must be reference-compatible, as described in Reference Compatibility in EGL.

scope = session, scope = request
Specifies when the PageHandler (the page bean) is removed from memory in the Web application server:
If scope is set to session (as is the default)
After the Web page is presented, the PageHandler remains in memory; then, if the user invokes a PageHandler function, the values returned from the Web page are available to the function--
  • If the function ends without issuing a forward, the JSF runtime code re-displays the same Web page without re-invoking the OnPageLoad function.
  • If the function ends with a forward statement that refers to the same page, the situation is the same as in the previous case; the OnPageLoad function is not re-invoked
  • If the function ends with a forward statement that refers to a different page, the data in the PageHandler is lost, although you may pass arguments and retain values in either the session or request object; for details, see forward
Even when the PageHandler scope property is set to session, the data in that PageHandler is not necessarily available throughout the user session. If PageHandler A forwards control to PageHandler B, for example, the data in PageHandler A is no longer available unless you took action like the following:
  • Included the data in arguments that are passed to the new PageHandler; or
  • Included the data in the session or request object; or
  • Included the data in a relational database or other data store.
If scope is set to request
After the Web page is presented, the PageHandler remains in memory, but is removed from memory as soon as the user submits another request. When the user invokes a PageHandler function, the following events occur:
  • The previous PageHandler is removed from memory
  • The requested PageHandler is started (or restarted), and the OnPageLoad function is invoked
  • The data received from the user is assigned to the related variables in the PageHandler
  • The PageHandler function runs, and the immediate events are the same as when the scope is set to session--
    • If the function ends without issuing a forward statement, the JSF runtime re-displays the same Web page without re-invoking the OnPageLoad function.
    • If the function ends with a forward statement that refers to the same page, the situation is the same as in the previous case; the OnPageLoad function is not re-invoked
    • If the function ends with a forward statement that refers to a different page, the data in the PageHandler is lost, although you may pass arguments and retain values in either the session or request object; for details, see forward

It is recommended that you set this property explicitly to document your decision, which affects the design and operation of your Web application.

throwNrfEofExceptions = no, throwNrfEofExceptions = yes

Specifies whether a soft error causes an exception to be thrown. The default is no. For background information, see Exception handling.

title = "literal"
The title property is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property specifies the title of the page.

literal is a quoted string.

validationBypassFunctions = ["functionNames"]
Identifies one or more event handlers, which are PageHandler functions that are associated with a button control in the JSP. Each function name is separated from the next by a comma.

If you specify an event handler in this context, the EGL runtime skips input-field and page validations when the user clicks the button or hypertext link that is or related to the event handler. This property is useful for reserving a user action that ends the current PageHandler processing and that immediately transfers control to another Web resource.

validatorFunction = "functionName"
Identifies the PageHandler validator function, which is invoked after all the field validators are invoked, as described in Validation in Web applications built with EGL. This property was formerly the validator property.
view = "JSPFileName"
Identifies the name and subdirectory path to the Java Server Page (JSP) that is bound to the PageHandler. JSPFileName is a quoted string.

The default value is the name of the PageHandler, with the file extension .jsp. If you specify this property, include the file extension, if any.

When you save or generate a PageHandler, EGL adds a JSP file to your project for subsequent customization, unless a JSP file of the same name (the name specified in the view property) is already in the appropriate folder (the folder WebContent\WEB-INF). EGL never overwrites a JSP.

viewRootVar = "variableName"
Identifies the name of a variable of type UIViewRoot, as is used to access the JSF component tree. For details, see viewRootVar property.

Related concepts
Overview of EGL properties
PageHandler
viewRootVar property

Related reference
PageHandler part in EGL source format

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.