Using the SAS Remote Browser :: SAS(R) 9.3 Companion for z/OS, Second Edition

What Is the Remote Browsing System?

The remote browsing system enables users who access SAS through a 3270 emulator (or a real 3270) to view SAS documentation from a Web browser on the user's PC. Previously, all documentation was displayed by the item store help in the SAS Help Browser window in the 3270 display. By displaying this documentation in your Web browser, you have better browsing capability and more complete documentation content.

Starting the Remote Browser Server

Remote browsing is invoked when SAS displays HTML output, usually from ODS, the Help system, or from the WBROWSE command. SAS attempts to detect your computer's network address and send remote browser requests to it. If you have not installed the remote browser server on your computer, SAS displays a dialog box that contains the address that is necessary to download the installer. The help server provides the remote browser installer, so you do not have to end your SAS session to install the remote browser server. Copy the address in the dialog box to your browser, download the installer, and run it. The installer places the remote browser server in the Startup Items folder, so that it will start each time you start your computer.

Setting Up the Remote Browser

Overview of Setting Up the Remote Browser

After the remote browser server is running on your computer, you can run the help by using the defaults for the HELPBROWSER, HELPHOST, and HELPPORT system options. If the HELPHOST option is not coded, SAS attempts to connect to the remote browser at the network address to which your computer's 3270 emulator (or your 3270 terminal) points. If the address is not the correct address for the remote browser, you will have to set the appropriate value for the HELPHOST option.

The HELPBROWSER system option specifies whether you want to use the new help (REMOTE, the default) or the traditional item store-based help (SAS) that uses the SAS Help browser. See the SAS System Options: Reference for more information.
The HELPHOST system option specifies the network name of your computer, which runs the remote browser server. If the HELPHOST option value is not specified, it defaults to the network address of the computer that is running your 3270 display emulator. This computer is usually the same computer that is running the remote browser server. For more information, see HELPHOST System Option: z/OS.
The HELPPORT system option specifies the port number that the remote browser server is listening on. The default port is 3755, the port that is registered for the Remote Browser Server. For more information, see the SAS System Options: Reference.

You can set these options at SAS invocation, in your configuration file, or during your SAS session in the OPTIONS statement or in the OPTIONS window.

Example 1: Setting Up the Remote Browser at SAS Invocation

The following code shows you how to set up the remote browser at SAS invocation:

sas o('helphost=mycomputer')

Example 2: Setting Up the Remote Browser during a SAS Session

The following code shows you how to set up the remote browser during your SAS session:

options helphost=mycomputer;

Remote Browsing and Firewalls

For General Users

If your network has a firewall between desktop computers and the computer that hosts SAS, browsers cannot display Web pages from your SAS session. Usually this is indicated by a time-out or connection error from the Web browser. If you receive a time-out or connection error, contact your system administrator.

For System Administrators

To enable the display of Web pages when a firewall exists between desktop computers and SAS, a firewall rule must be added that enables a browser to connect to SAS. The firewall rule specifies a range of network ports for which SAS remote browsing connections are allowed. Contact the appropriate administrator who can select and configure a range of firewall ports for remote browsing. The range size depends on the number of simultaneous SAS users. A value of approximately three times the number of simultaneous users should reserve a sufficient amount of network ports.

Once the firewall rule has been added, SAS must be configured to listen for network connections in the port range. Normally, SAS selects any free network port, but the HTTPSERVERPORTMIN and the HTTPSERVERPORTMAX system options limit the ports that SAS selects. Add these options to your SAS configuration file. Set the HTTPSERVERPORTMIN option to the lowest port in the range. Set the HTTPSERVERPORTMAX option to the highest port in the range. For example, if the network administrator defines a port range of 8000–8200, the system options are set as follows:

httpserverportmin=8000
httpserverportmax=8200

After the firewall rule is added and these system options are set, desktop computers can view Web pages through the firewall. If there are insufficient ports or the system options are specified incorrectly, a message displays in the SAS log.

For more information about these options, see “HTTPSERVERPORTMIN= System Option” and “HTTPSERVERPORTMAX= System Option” in the SAS System Options: Reference.

Converting Item Store Help to HTML Help

Overview of Converting Item Store Help

The SAS 9.2 remote browser does not read item store help files. The SAS %ISHCONV macro enables you to convert your item store help files into HTML files that you can use with the remote browser.

Note: If your location uses item store help files with SAS, then your SAS system programmer is the person who usually converts the item store files to HTML files. Contact your system programmer if you cannot access the HTML help files.

Creating a Common Directory

In order for SAS users at your location to access your HTML help files with the remote browser, you need to create a common directory in UFS. The common directory contains the HTML files that are created by the %ISHCONV macro. It can also contain subdirectories that contain more HTML files. The %ISHCONV macro uses the htmdir parameter to specify the common directory if you do not create it before running the macro. However, you have to specify a directory pathname for the htmdir parameter, so it is best to create the directory before you convert the item store files.

The common directory should allow all SAS users at your location to access the files, so you should place it in a directory path that is accessible to them. As always, it is a good idea to determine the best location for the directory before you create it and put your files in it. Such planning can prevent you from having to move the directory and its files at a later date.

Converting Your Files to HTML

The SAS macro, %ISHCONV, converts your item store files into HTML files. %ISHCONV uses the ishelp and ishref parameters to specify the data set name of the catalog that contains the item store help and the member of the item store help. It uses the exphlp and htmdir parameters to specify the filename of a work file for conversion processing and the pathname for the HTML files.

Note: The converted HTML files have a file extension of .htm.

For more information about using %ISHCONV to convert your item store files to HTML, see %ISHCONV Macro: z/OS.

Adding HELPLOC Path Values

The INSERT system option enables you to add new path values to the HELPLOC option. Path values that are added with the INSERT option are read before paths that are already assigned to the HELPLOC option in your configuration file. You can insert multiple paths for the HELPLOC option.

The following commands insert a new path value for the HELPLOC option before other paths that are specified in your configuration file. The following example inserts a path in a directory that contains files in ASCII:

-insert (helploc='/u/userid/ishconv_dir_ascii')

The following example inserts a path in a directory that contains files in EBCDIC:

-insert (helploc='/u/userid/ishconv_dir_ed–1047;ebcdic')

After you use the INSERT command to assign additional path values, you can issue the following command:

proc options option=helploc; run;

To display the new value for HELPLOC that combines the two paths:

HELPLOC=( '/u/userid/ishconv_dir_ascii'
        '/u/userid/ishconv_dir_ed-1047;ebcdic'
        '/usr/local/SASdoc' )

The path value '/usr/local/SASdoc' is the value that was set for HELPLOC in your configuration file.

Accessing Your HTML Help Files

After your item store help files are converted to HTML, you can access the HTML help files by the same methods that you used to access the item store help:

Select Help from the SAS menu bar.
Enter the HELP command from the SAS command line.

The SAS HELP command:

help helploc://user.hlp/index.htm

accesses the index.htm file in the UFS directory that has the fully qualified name:

/u/userid/ishconv_dir_ascii/user.hlp/index.htm

Note: You are not limited to using the HELP command to access only the index.htm file of your help. You can issue the HELP command to access Help with the remote browser for Windows, SAS language elements, and so on, the same as you have with previous SAS Help systems.

If a help file with the same relative path and filename exists in multiple HELPLOC path values, SAS displays the file from the first path that is encountered. This feature enables you to amend an existing file that is available to SAS.

If you get an error message that the help is not available, use the HELPLOC system option to specify the location of the help files. You can include the HELPLOC option in your configuration file, or you can issue it at SAS invocation. Contact your system programmer for the location of the help files that you need to use with the HELPLOC option.

Creating User-Defined Help Files in HTML

You can write your own HTML help files to use with SAS. Use the same tools or file editors to write these HTML files that you would use to write any other HTML files. After you have written these files, place them in a location where SAS can access them. If your HTML help files are encoded in EBCDIC, you need to include the ;ebcdic attribute in the declaration for the HELPLOC system option. For information about working with ASCII-encoded files in the z/OS USS environment, see the IBM z/OS UNIX System Services User's Guide.

For information about using the HELPLOC system option, see HELPLOC= System Option: z/OS.

Note: SAS provides the ITEMS procedure to enable you to produce item store files, but we encourage you to create and use HTML help files. Any item store file that you create is used with SAS item store files that have not been updated for this release of SAS.

Using Remote Browsing with ODS Output

The SAS Output Delivery System can be used to generate graphical reports of your SAS data. Remote browsing enables you to view your output directly from the SAS session, either in real time as the output is generated, or on demand from the Results window.

Remote browsing displays ODS output that is generated to z/OS native data sets (sequential, PDS, or PDSE) or a UFS directory. HTML, PDF, RTF, and XLS file types are displayed with the remote browsing system. If your browser does not have the appropriate plug-in for non-HTML data types, it will display a download dialog box rather than the actual data. This dialog box will enable you to download the report to your PC and view it using a local program, such as Excel for an XLS file.

Note: When images or graphics are written to az/OS native data set and remote browsing is being used to view the output, the URL=NONE option should not be used with the ODS statement. Using this option causes the HTML to be written with incomplete filenames, and the remote browsing system is not able to determine the location of the image or graphics. When this situation occurs, the browser displays broken image icons in the HTML output.

The automatic display of ODS output is turned off by default. You can turn on the automatic display of ODS output by issuing the AUTONAVIGATE command in the Results window.

For more information about viewing ODS output with a browser, see Viewing ODS Output on an External Browser.

Using the SAS Remote Browser