WebFOCUS Script Commands

How to:

Reference:

You can use WebFOCUS Script (WFS) commands with WebFOCUS Client settings (see WebFOCUS Administration Console) and HTTP header variables (see HTTP Header Variables Available for Script Processing) to further customize processing and control of the WebFOCUS Client.

You can use WFS commands to:

Tip: You can also use the following variables with WebFOCUS script commands:


Top of page

x
Reference: WFS Command Syntax

You can place the following WFS commands in site.wfs or in the node profile of a specified server.

Command Syntax

Description

<EXIT>

Causes the WebFOCUS Client to stop processing and exit immediately.

<HTMLFORM> filename

Displays an HTML page and allows for variable substitution in the HTML document. For more information, see How to Display an HTML Page With Variables.

<INCLUDE> filename

Separates WFS logic outside of the standard WFS files. The file must exist for processing to continue. For more information, see How to Separate WFS Logic Outside of Standard WFS Files.

<CONDITIONAL_INCLUDE>  
filename

Works in the same manner as <INCLUDE> filename except that the file does not need to exist. For more information, see How to Separate WFS Logic Outside of Standard WFS Files.

<SET> variable_name(option)

Allows the validation and control of WebFOCUS Client variables. For more information, see How to Enable Validation and Control of Variables.

<CALL> function(parm1,...)

Invokes WebFOCUS plug-ins. Each WebFOCUS plug-in can contain a maximum of 10 input parameters. For more information, see How to Invoke the WebFOCUS Servlet Plug-in.

<IF> variable operator 
value 
<ELSE>
<ENDIF>

Allows the conditional checking of WebFOCUS Client variables. For more information, see How to Conditionally Check Variables.

<IFDEF> variable 
<ELSE>
<ENDIF>

Checks for the existence of a WebFOCUS Client variable. For more information, see How to Check for the Existence of a Variable.

<IFNDEF> variable 
<ELSE>
<ENDIF>

Checks to see if a WebFOCUS Client variable does not exist. For more information, see How to Check If a Variable Does Not Exist.

<SENDVAR> 
name={constant|&value}
<ENDSENDVAR>

Sends variables to the WebFOCUS Reporting Server for use with server procedures. It is used for variables that are not automatically sent to the WebFOCUS Reporting Server. For more information, see How to Send Variables to the WebFOCUS Reporting Server.

Note: This syntax has been deprecated. It is recommended that the <SET> variable_name (option) is used instead of the <SENDVAR> technique.

<DBA_PASS>

Prepares the SET PERMPASS=(user) syntax by processing the value of IBIF_dbapass_src (found in the cgivars.wfs file). Used in DEFAULT.WFS to populate the value of an internal variable (_ibi_dbapass) that is used to build the FOCEXEC prefix.

<DBA_PASS> always sets the _ibi_dbapass variable to one of the following values:

  • \n (newline) when value of IBIF_dbapass_src is blank.
  • The processed file name when IBIF_dbapass_src is set to CURRENT_USER_FILE or IBIMR_domain.
  • The value of the variable when a variable name is stored in IBIF_dbapass_src.


x
Reference: WFS Language Syntax

When coding WFS commands, you can use the following syntax:

Command Syntax

Description

<! >
#

Comment character you can add at the start of any line. It tells the WebFOCUS Client that the current line is a comment.

For example:

<! This is a comment.> 
# This is also a comment.
\\=

Continuation character you can add at the end of any line. It tells the WebFOCUS Client that the next line is a continuation of the current line. For example:

long_string = this is a \\=
very long string that \\=
needs multiple lines 
\n

Carriage return line feed that enables you to put multiple commands on a single line.

value = 
{constant|&variable}

Assigns a value to a variable in a WFS file as either a constant or a variable, where:

constant

Is a literal value. If you include quotation marks, they are passed in as part of the variable.

Note: If the constant contains special characters, for example, & or \, the backslash (\) can be used as an escape character to ensure that the special character is passed as part of the value.

&variable

Is a placeholder for a value.

Once a variable has been assigned a value, you can use the variable name (prefixed with an ampersand) in place of the value. You can concatenate literal values in this way. For example:

long_string = this is a 
long_string =&long_string very long string 
long_string =&long_string that requires 
multiple lines


x
Reference: Backslash Escape Character

When a backslash (\) is used as the escape character, you can:

When a backslash is used as an escape character, it is not included in the length of the string.



Example: Using a Backslash Escape Character

You can include a backslash escape character within a string as part of the value by preceding it with a second backslash. For example, the following source code:

COMPUTE Line/A40 = 'The characters \\\' are interpreted as \'';
.
.
.
TYPE "Escape info: <Line"

displays:

Escape info: The characters \' are interpreted as '

When the backslash is used as an escape character, it is not included in the length of the string. For example, a string of five characters and one escape character fits into the following five character variable:

COMPUTE Word/A5 = 'Can\'t'

Top of page

x
Syntax: How to Use Variables to Affect WebFOCUS Reporting Server Output

WebFOCUS Client variables give you control over the display of multiple reports on the same HTML page with multiple frames without coding HTML FRAME syntax. It also allows you to link multiple reports with a single Table of Contents (TOC) that calls them. For example, you can use these variables to display different report formats, such as HTML and PDF, on a single launch page. To affect the output of requests coming back from the WebFOCUS Reporting Server, issue the following syntax on the WebFOCUS Reporting Server.

-TYPE WEBFOCUS CGIVAR varname=value

where:

varname

Is the name of the WebFOCUS Client variable.

value

Specifies the value of the WebFOCUS Client variable.

For more information about WebFOCUS Client variable names and possible values, see Controlling Multiple Reports in the Enhancing a User Interface chapter of the Developing Reporting Applications manual.


Top of page

x
Syntax: How to Display an HTML Page With Variables

The following command displays an HTML page

<HTMLFORM> filename<@--#echo var="variable"--> text

where:

filename

Is the name of the HTML file to be displayed.

The contents of the HTML document should use standard HTML syntax, and may include JavaScript. The following syntax may be added to the HTML document for variable substitution

<@--#echo var="variable"--> text

where:

variable

Is the WebFOCUS Client variable.



Example: Displaying an HTML Document

The following is the source code of HTML document wfexterr.htm, which displays an error page for a WebFOCUS plug-in:

<HTML>
<HEAD>
<TITLE>WebFOCUS External Security Plug-in</TITLE>
</HEAD>
<BODY>
<h1><i><font color="#000080">WebFOCUS</font></i></h1>
<H3><HR>
<A HREF="/ibi_html/wfext.html"
onClick="window.location='/ibi_html/wfext.html';return false">
<@--#echo var="seccode"--></A> not authorized to use WebFOCUS, status=<@-
#echo var="RETCODE"-->
<HR></H3>
</BODY>
<!--
rc=96000
-->
</HTML>

Note: The code beginning with <!-- and ending with --> is required by Dashboard.

The following command displays wfexterr.htm:

<HTMLFORM> wfexterr.htm

This HTML document appears on the browser as follows:

HTML Document image


Top of page

x
Syntax: How to Separate WFS Logic Outside of Standard WFS Files

The following command allows a custom WFS file to be called from standard WFS files. The file must exist for processing to continue.

<INCLUDE> filename

where:

filename

Is the name of the file to be included for WFS processing.

<CONDITIONAL_INCLUDE> filename works in the same manner as <INCLUDE> filename except that the file does not need to exist.



Example: Separating WFS Logic Outside of Standard WFS Files

The following command checks for a file called custom.wfs. If the file exists, it is included for WFS processing. The variable CGI_BASE_DIR is a standard WebFOCUS variable that you can edit in the WebFOCUS Administration Console. The WebFOCUS installation sets the variable DirSep to the directory path delimiter for your operating environment (forward slash for UNIX, back slash for Windows):

_exit=custom.wfs
<CONDITIONAL_INCLUDE> &CGI_BASE_DIR&_DirSep&_exit

Top of page

x
Syntax: How to Enable Validation and Control of Variables

The following <SET> command enables validation and control of WebFOCUS Client variables passed from a cookie or form:

<SET> variable_name (option)

where:

variable_name

Is the name of the WebFOCUS Client variable.

option

Can be one of the following:

  • pass - The variable becomes a Dialogue Manager amper variable on the WebFOCUS Reporting Server. This is the default value.
  • dontpass - The variable will not be passed to the WebFOCUS Reporting Server.
  • protect - The variable cannot be set from the browser.

    Note: The variables IBIF_focexec and IBIF_ex should not be restricted with the protect option. Doing so would prevent WebFOCUS from executing the procedure.

  • number - The variable allowed can only be numeric.
  • alpha - The variable allowed can only have alphanumeric characters [0-9, a-z, period (.), underscore ( _ ), hyphen (-), exclamation point (!)].
  • string - All characters are valid.
  • length=n - Sets the maximum length of a variable in characters. The length is unlimited by default.

For an example of the <SET> command, see Using Alphanumeric Characters in IBIF_ex.



Example: Using Alphanumeric Characters in IBIF_ex

For non-Managed Reporting requests, only alphanumeric characters may be passed to IBIF_ex, which is the name of a WebFOCUS Reporting Server procedure. The following <SET> statement controls IBIF_ex so that it only accepts alphanumeric characters.

<if> IBIMR_drill EQ NULL AND IBIMR_action EQ NULL
<SET> IBIF_ex(alpha)
<endif>

Top of page

x
Syntax: How to Invoke a WebFOCUS Plug-in

The following command invokes WebFOCUS plug-ins:

<CALL> function(parm1,parm2,...parm10)

where:

<CALL>

Is the command that invokes the WebFOCUS plug-in.

function

Defines the name of the actual function to be called (for example, security).

(parm1,parm2,...parm10)

Are the input parameters of the WebFOCUS plug-in. Each WebFOCUS plug-in can contain a maximum of 10 input parameters. The output buffer is not passed in as a parameter in this statement.

Note: The value of RETCODE can be checked to determine whether the plug-in function succeeded or failed.

For more detailed information about WebFOCUS plug-ins, see Copying WebFOCUS Variables Using the WebFOCUS Servlet Plug-in.



Example: Using WFS Script Commands

The following example makes use of a number of WFS scripting commands.

  1. Check that variable seccode is passed in from the HTML form. If seccode is not passed in, an HTML error page displays and processing stops.
    <ifndef> seccode 
       <HTMLFORM> &IBI_HTML_DIR /wfext.html
       <EXIT>
    <endif>

    Note that when you connect to WebFOCUS from Developer Studio, messages embedded in <HTMLFORM> tags are not supported.

  2. Invoke a WebFOCUS plug-in (called security).
    <CALL> security(seccode)
  3. Check for a valid return code. If the return code is valid, values are assigned to WFS variables. An invalid return code displays an HTML error page and exits.
    <if> RETCODE EQ "0"
        IBIC_pass   = &wfepass 
        IBIC_user   = &wfeuser 
        IBIC_server = &wfenode 
    <else>
       <HTMLFORM> wfexterr.htm
       <EXIT>
    <endif>

Top of page

x
Syntax: How to Conditionally Check Variables

The following <IF> statement conditionally checks WebFOCUS Client variables.

<IF> variable operator value 
<ELSE>
<ENDIF>

where:

variable

Is any WebFOCUS Client variable.

operator

Can be set to EQ, NE, CONTAINS, OR, and AND.

value

Applies to any WebFOCUS Client variable or constant.


Top of page

x
Reference: Checking Variable Values in Uppercase

By adding upper to a WFS variable, the value will be checked as if it has all uppercase characters. This may be useful if you want to check the value that the user entered, without worrying about the case.



Example: Conditionally Checking Variables

You can use the following <IF> statement to ensure that the WebFOCUS logon page is invoked.

<IF> IBIC_user EQ NULL OR IBIC_user EQ ""
<HTMLFORM> &IBI_HTML_DIR/wfsignon.html
<EXIT>

Note that when you connect to WebFOCUS from Developer Studio, messages embedded in <HTMLFORM> tags are not supported.

The following <IF> statement ensures that any server value entered is not case-sensitive.

<IF> IBIC_server.upper EQ "SERVER"
# INSERT YOUR CODE HERE....
<ENDIF>

The following <IF> statement checks whether or not constant .ibi.com is contained in the WebFOCUS Client variable HTTP_HOST.

<IF> HTTP_HOST contains ".ibi.com"
# INSERT YOUR CODE HERE....
<ENDIF>

Top of page

x
Syntax: How to Check for the Existence of a Variable

The following <IFDEF> statement checks for the existence of a WebFOCUS Client variable.

<IFDEF> variable 
<ELSE>
<ENDIF>

where:

variable

Is any WebFOCUS Client variable.



Example: Checking for and Defining a Variable

In the following example, if the variable _ON_NT exists, PATH_SEP is set to a semicolon (;). If the variable ON_NT does not exist, PATH_SEP is set to a colon (:).

<ifdef> _ON_NT
PATH_SEP=; 
<else> 
PATH_SEP=: 
<endif>

Top of page

x
Syntax: How to Check If a Variable Does Not Exist

The following <IFNDEF> statement checks to see if a WebFOCUS Client variable does not exist:

<IFNDEF> variable 
<ELSE>
<ENDIF>

where:

variable

Is any WebFOCUS Client variable.

For an example, see Setting a Default Redirect Page.



Example: Setting a Default Redirect Page

The following example sets a default redirect page when a valid WebFOCUS sign-on is achieved.

<ifndef> WF_SIGNON_MESSAGE 
WF_SIGNON_MESSAGE=/ibi_html/default.htm
<endif>

Top of page

x
Syntax: How to Send Variables to the WebFOCUS Reporting Server

The following command sends variables to the WebFOCUS Reporting Server for use with server procedures. Certain custom variables are sent to the WebFOCUS Reporting Server automatically. This syntax is used for variables that are not automatically sent to the WebFOCUS Reporting Server.

<SET> name={constant|&variable} (pass)

where:

name

Is a Dialogue Manager variable to be used by the WebFOCUS Reporting Server.

constant

Is a literal value. If you include quotation marks, they are passed in as part of the variable. Applies to any WebFOCUS Client variable.

&variable

Is a placeholder for a value. Applies to any WebFOCUS Client variable.



Example: Sending User IDs to the WebFOCUS Reporting Server

The following example sends the WebFOCUS Reporting Server user ID to the WebFOCUS Reporting Server. It can be used from within any procedure.

<SET> CUSER=&IBIC_user (pass)

Note: It is recommended that the <SET> variable_name (PASS) is used instead of the <SENDVAR> technique.


WebFOCUS