Usage Note 12599: Using Java in a headless environment is not supported under z/OS
 |  |  |  |
What is headless Java?
Java's graphics capabilities were originally intended for client machines, which have built-in graphics cards. So, the initial Java implementation assumed that requests to create graphics could make use of the graphics card of the machine on which Java was running. As Java became a server-side technology, graphics creation also moved to the server. Then it became useful to create graphics in memory on servers. Those graphics could be saved in files or sent over the network to be displayed on other machines. However, servers often do not have graphics cards. They are often administered remotely without using attached displays. So, Java could no longer assume that it was running on a machine that had graphics hardware. Java was redesigned to allow some, but not all, graphics functions to be performed in a headless environment. As a result, some Java graphics functions now work without using a graphics device.
Why is headless Java important to SAS?
SAS® graphics components use headless Java to produce graphics files. These files are not necessarily created on the device where they will be displayed. They can, for example, be created on a server running in a SAS backend tier. Headless Java makes it easy for SAS customers to use SAS without having to worry about providing graphics cards on all of the servers which SAS might produce graphics files. Using headless Java, SAS can create graphics on servers that have no graphics hardware, and SAS does not have to require or support the use of such hardware.
What are the potential problems with headless Java?
Sun implemented headless Java in its Java 1.4.0 offering, and most of the other Java vendors that SAS uses did the same. However, IBM did not. IBM provided a headless Java implementation that throws HeadlessExceptions, but does not allow the creation of graphics files. A description of the HeadlessException is available in the documentation for Java 2 Platform Std. Ed. v1.4.2.
So, while SAS graphics components are able to take advantage of headless Java from other vendors, they will be unable to do so with IBM SDKs or JREs released earlier than Java 1.4.2. IBM Java 1.4.2 is expected to include IBM's first implementation of headless Java. Until IBM releases its headless Java implementation, SAS will support its customers using IBM Java in cases where graphics devices are not available for SAS. This support includes installation and workarounds for the situations in which headless Java cannot be used.
When is this a problem?
As discussed above, headless Java will not work correctly if you are using an IBM Java SDK or JRE that was released earlier than Java 1.4.2. SAS customers might be trying to use an earlier release of IBM Java to produce graphics in the following cases:- They might be using SAS software that runs outside of an application server (Tomcat, WebLogic, or WebSphere) under z/OS.
- They might be using SAS software that executes Java code inside WebSphere under Windows or AIX. In this case, WebSphere uses its own Java SDK.
When IBM Java from a release earlier than 1.4.2 is used, the command line that starts IBM Java should NOT include the option -Djava.awt.headless=true and the java.awt.headless property must not be set to true in the Java application code. java.awt.headless is the Java property used to enable headless Java. Using the headless property will cause IBM Java to throw HeadlessExceptions instead of producing graphics files.
Removing the -Djava.awt.headless=true option from the Java command line in WebSphere is enough to fix the headless problem when WebSphere is running under Windows. WebSphere Java will then use the graphics card in the machine that is running Windows. Other steps are needed, however, to provide a workaround for headless Java under z/OS.
What are possible circumventions?
Because the -Djava.awt.headless=true option cannot the used in the above cases, customers that need to use an IBM Java that is earlier than 1.4.2 need to configure their z/OS system using one of the following circumventions:- Give Java the address of a machine that has an X server running and a graphics device that Java can use to produce graphics.
- Give Java the address of a machine that has an X server running with a dummy graphics adapter (XVFB).
What is the X server address?
Regardless of which z/OS workaround is chosen, the address of a machine running an X server has to be provided to the process that is running IBM Java. Under z/OS, this is done by setting the TKJNI_OPT_DISPLAY option in the TKMVSENV data set that is used to simulate environment variables when SAS is running in TSO. For example, a TKJNI_OPT_DISPLAY entry might look like this:
set TKJNI_OPT_DISPLAY='unixwrk01.company.com:0' asis
(Contact your network support group if you do not know what a valid X server or X server pool name is in your shop. The server name used here is provided only as an example for how to set this value.)
Examples of TKJNI_OPT_DISPLAY usage might be to specify a PC running Exceed somewhere on an intranet, or the address of the same machine where SAS is running, if that machine contains a graphics card.
When a graphics device is not available, what steps need to be taken?
Xvfb is available for z/OS through the IBM Ported Tools for z/OS. It is available free of charge to those sites that have z/OS licensed. For information on obtaining information on these tools or to order them, refer to Xvfb for z/OS.
Refer to the IBM Ported Tools for z/OS: Xvfb User's Guide for information about starting Xvfb and the options that are supported.
You can activate the Xvfb server under z/OS, for example, the server is installed in the default UNIX File System path /usr/lpp/tcpip/bin/X11. From that path, if you issue the USS command ls -l there will be two files (Xvfb and uil), and one directory (samples). The permissions for Xvfb should be -rwxr-xr-x. You can run the Xvfb executable along with the appropriate options to get the X server running. However, it is probably easier to change directory to the samples folder and run the startXvfb.sh shell script. The default $HOMEDIR path will be the aforementioned UNIX File System path. The default Server/Display number is 8.
For SAS to use the z/OS Xvfb server, set the TKMVSENV environment variable TKJNI_OPT_DISPLAY. This option is assigned the the value of server:displaynum, where server is the host name where the z/OS Xvfb server is running and displaynum is the Server/Display number. So if the host name is PRODZOS and the Server/ Display number is 8 then the variable is set as follows:
set TKJNI_OPT_DISPLAY='prodzos:8' asis
Operating System and Release Information
| Product Family | Product | System | SAS Release | |
| Reported | Fixed* | |||
| SAS System | Base SAS | z/OS | 9.1 TS1M0 | |
| 64-bit Enabled AIX | 9.1 TS1M0 | |||