Open Method (CLIENT)

PLB Web Only, 9.7

 

The Open method opens a new Browser window. The method uses the following format:

 

[label]

{object}.Open

[GIVING {return}] USING [[*URL=]{url}][:

 

 

[*Options=](options}][:

 

 

[*Name=]{name}][,[*Specs=]{specs}]

 

Where:

label

Optional. A Program Execution Label.

object

Required. A CLIENT object.

return

Optional. A Numeric Variable that returns the success or failure of the method.

url

Optional. A Character String Variable or string literal that defines the initial page to be displayed.

options

Optional. A Numeric Variable or decimal number as defined below.

name

Optional. A Character String Variable or string literal that defines the browser's window. (9.7C)

specs

Optional. A Character String Variable or string literal that defines the browser's window specifications. (9.7C)

Flags Affected: OVER, ZERO

Note the following:

  1. The ZERO flag is set when the {return} value is zero.

  2. The OVER flag is set if the value returned is too large to be stored into the {return} variable.

  3. The {options} value is available for use to implement special behaviors for this method.

    4.  

    Value

    Definition

    0x0

    If the {options} parameter is not used or the {options} value is zero, the default behavior for the 'Client.Open' method is to open a new browser window and load a web page link as described for a browser Window object 'open' method. In this case, the {url}, {name}, and {specs} parameters can be used.

    0x1

    If the {options} parameter bit value of 1 is being used, the 'Client.Open' method executes in a mode that allows a 'Save-As-Dialog' to appear at the browser client which allows a file name specified in the {url} string to be opened or saved at the client browser. In this case, the {url} must be a file name that can include a relative path specified by a sub-directory to the path declared in the 'PLBWEB_SAVETOCLIENT' keyword. Also, the {name} and {specs} parameters are ignored when using this {options} bit value. The presentation of the 'Save-As-Dialog' is controlled and depends solely on the client browser behaviors."

     

  4. Depending on the {options} bit value being used, the {url} string can be either a link to any web server web page or it can be a file that is located on the PL/B Web Server.

    5.  

    When the {options} bit value is zero, the {url} string may be a link to a web server from which a web page may be loaded into the new browser window. It should also be noted that the {url} string could actually start another PL/B program in the new browser window. See the following link for more information on the definition\syntax of a URL:

     

    http://en.wikipedia.org/wiki/Uniform_resource_locator

     

    Example of {url} string:

     

    Client.Open USING *URL="http://www.sunbelt-plb.com"

     

    This instruction causes the Sunbelt Web Server web page to show in a new browser window.

     

    Client.Open USING *URL="http://www.sunbelt-plb.com:8081/images/sunbelt.png"

     

    This instruction allows the Sunbelt PL/B Web server to download the image located and named '/usr/plbwebsrv.97b/http-root/images/sunbelt.png' to the client browser. In this case, the image is rendered by the client browser so it appears in a new client browser window.

     

    When the {options} bit value is 0x0001, the {url} string must be a file name for a file that can be found in a sub-directory defined by the keyword named 'PLBWEB_SAVETOCLIENT={subdirectory}'. In this case, the PL/B Web Server downloads the specified file to the client browser using a HTTP 'content-disposition' header to cause the client browser to invoke the 'Save-As-Dialog' so the {url} string file can be saved at the client browser. If the 'PLBWEB_SAVETOCLIENT' keyword is not used, the PWS defaults to only down files found in the PWS sub-directory named 'savetoclient' that is found in the PWS 'http_root' directory.

     

    Example of {url} string without 'PLBWEB_SAVETOCLIENT' keyword:

     

    Client.Open USING *URL="sunbelt.png",*OPTIONS=1 //Force Save-As-Dialog!

     

    This instruction allows the Sunbelt PL/B Web server to retrieve the image named 'sunbelt.png' from the PWS sub-directory named 'savetoclient' under the 'http_root' directory. The image is downloaded to the client browser where the browser invokes the 'Save-As-Dialog'. In this case, the 'savetoclient' directory is the default sub-directory name that is used when the 'PLBWEB_SAVETOCLIENT' keyword is not defined for the PWS server.

     

    Example of {url} string with 'PLBWEB_SAVETOCLIENT' keyword being used. Entry in the plbwebsrv.ini file:

     

    [environment]

    PLBWEB_SAVETOCLIENT=myimages

     

    When the PL/B Web Server is first loaded, this keyword defines the sub-directory under the PWS 'http_root' directory which contains files that can be downloaded to a client browser when the browser invokes the 'Save-As-Dialog'.

     

    Client.Open USING *URL="sunbelt.png",*OPTIONS=1 //Force Save-As-Dialog!

     

    This instruction allows the Sunbelt PL/B Web server to retrieve the image named 'sunbelt.png' from the PWS sub-directory named 'myimages' under the 'http_root' directory. The image is downloaded to the client browser where the browser invokes the 'Save-As-Dialog'.

  1. The {name} string usage is optional and may be used when the {options} value is zero. The {name} string can be specified the same as defined for a browser WINDOW object 'name' parameter for the 'open()' method. See the following link for details of possible strings that can be used.

    2.  

    http://www.w3schools.com/jsref/met_win_open.asp

     

  2. The {specs} string usage is optional and may be used when the {options} value is zero. The {specs} string can be specified the same as defined for a browser WINDOW object 'specs' parameter for the 'open()' method. See the following link for details of possible strings that can be used.

    3.  

    http://www.w3schools.com/jsref/met_win_open.asp

     

  3. The operations of the 'Client.Open' method depends on the current configuration\settings of the client browser and the Web Server being accessed via the {url} string. Depending on these configuration\settings the 'Save-As-Dialog' may or may not be shown on the client browser.

  4. The CLIENT 'Open' method {return} values are defined as follows:

    5.  

    Return Value

    Description

    0

    The client browser 'window.open' JavaScript function returned a browser Window object. The browser 'window.open' JavaScript operations are strictly controlled by the browser in conjunction with the current configuration settings of the browser. Thus, even when the 'window.open' returns a browser Window object, the subsequent browser operations may fail due to some URL accessibility issues which are not known to the PL/B program environment.

    10

    The client browser 'window.open' JavaScript function returned a null browser Window object. In this case, there is a failure and there is no specific description of the error available. However, it should be noted that this error can occur when the Client Browsers are configured to 'Block Popups'.

    11

    The client browser 'window.open' JavaScript function has encountered a 'exception' error. The 'exception' error description is currently not available to the PL/B program.

 

 

See Also: CLIENT, Client Methods, Method Syntax

 


PL/B Language Reference JqSet Method (CLIENT) Print Method (CLIENT)