Skip to end of metadata
Go to start of metadata


Virtual Network Computing (VNC)

A free X window server running natively on IBM i


Virtual Network Computing (VNC) is a free X window server running also natively on IBM i. VNC offers to SAP customers on IBM i the possibility  to run GUI related SAP tools directly on i. 


Ralf Büscher

Company:   IBM Deutschland  
Created on:   Jul. 13, 2011
Author(s) Bio
I'm working since 1998 for IBM. Starting with 2002 I'm part of the SAP on IBM i porting team.


Starting with IBM i 5.4, the product 5799PTL (IBM Tools for Developers for i5/OS) includes VNC. VNC is an X window server running natively on IBM i. This means that the graphical output of a program is handled on IBM i and only the presentation of the output is done by a client software on Windows or Linux. This offers the possibility to use GUI related SAP tools directly without starting every single time an extra program or browser for presenting the graphical output. Once the VNC software is available and started you can start any GUI related tool without extra work to make the output visible. Especially the stopping and restarting of a tool becomes easier.

VNC should be used by experts only. It is not officially supported by SAP. The supported way to start an SAP tool is described in the SAP installation documentation or the SAP Help.

This How-to page promotes VNC. It shall motivate SAP customers on i to try out whether VNC helps them to work more efficiently with GUI related SAP tools on IBM i.

A sufficient and complete description of VNC on i is available from IBM. You can find the IBM documentation using this url:


There are two typical scenarios to use VNC as an SAP customer. First the installation of new SAP systems and second the maintenance of already running SAP systems.
For installation you run the tool SAPinst using an installation user (for example SAPIUSR) and for some maintenance tasks you are running the tools JSPM and Configtool using the SAP system user <SID>ADM.
Once you have a running VNC for the installation user or the SAP system user you can start the GUI related tools directly on IBM i. No program or script like SAPinstGUI.exe, StartGui.bat or configtool.bat has to be started on Windows. No additional connect between the SAP tool on IBM i and the SAP GUI tool on Windows has to be established. No extra parameter like '-nogui' has to be added to the command call of the SAP tool started on IBM i. VNC can help to make the handling of GUI related SAP tools much easier and more convenient.

How-to use VNC

The next sections describe in detail the use of VNC. Especially the handling of the three GUI related tools SAPinst, JSPM, and Configtool is explained.

I. Initial Preparation of VNC (only done once)

  1. The IBM i host has to run with IBM i 5.4 or higher.
  2. Make sure the product IBM Tools for Developers for i5/OS (5799PTL) is installed on the IBM i host. Perform the following command:
          a. GO SOFTWARE
          b. Choose option 10 (Display installed licensed programs).
    Check for the Licensed Program 5799PTL which has to have the Installed Status *INSTALLED. If the product is missing contact your IBM i administrator. The product itself is free.
  3. Download and install the VNC viewer to your Windows PC. Go to and follow the link to the download area.
    You can use the Free Edition, and you only need the VNC viewer, though it might be packaged with a VNC server. (The needed VNC server is already installed on the IBM i host as checked already in the last step.) 
    As an example for Windows XP download the file vnc-4_1_3-x86_win32_viewer.exe. (This file is just a program. It does not have to be installed. A double-click on it is enough to start it.)
    Note: Beside RealVNC there are other vendors offering a free VNC viewer like UltraVNC ( or TightVNC (

II. Initial Preparation of an IBM i User for VNC (only done once per user)

Create a VNC password file for your IBM i user you plan to use for VNC (for example the SAP system user <SID>ADM or the installation user SAPIUSR - the creation of an installation user is described in the installation documentation). You only need to do this the first time you want to use VNC or when you want to change your VNC password. Create a file named passwd containing your encrypted password by running the following commands on your IBM i host:
      a. MKDIR '/home/<IBM_i_user>/.vnc'
      b. QAPTL/VNCPASSWD USEHOME(*NO) PWDFILE('/home/<IBM_i_user>/.vnc/passwd')
The command VNCPASSWD will create the file passwd and it asks for the VNC password for the IBM i user. The VNC password has to be 6 to 8 characters long and it should be different to the logon password of the IBM i user.

III. Starting the VNC Server and the VNC Client

  1. Logon as the IBM i user prepared for VNC (for example the SAP system user <SID>ADM or the installation user SAPIUSR).
  2. Start the VNC server. Run the following command:
  3. When the server starts you will see a message similar to the following:
    New '<IBM i hostname>:1 (<IBM i user>)' desktop is <IBM i hostname>:1.
    Now the variable DISPLAY is set to 'IBM i hostname:1' in the environment of your IBM i user.
    Press ENTER to continue using your session.

    Note: Each time another VNC server for a different IBM i user is started, you will see a different number in the place of :1 in the example above. You cannot start multiple VNC servers for the same IBM i user.
    Note: To use VNC from multiple sessions of the same IBM i user you have to set the same environment variable DISPLAY in every needed session using the following command:
          ADDENVVAR ENVVAR(DISPLAY) VALUE('<IBM i hostname>:<n>')
  4. Start the VNC viewer on your PC. For example double-click onto the program vnc-4_1_3-x86_win32_viewer.exe you have downloaded earlier. 
  5. When the VNC viewer is asking for Connection Details put into the field called Server: 
          <IBM i hostname>:<n>

    Note: Only one RealVNC viewer can be connected to a VNC server at the same time. Every connect of a new RealVNC viewer to the VNC server will stop the old viewer(s). The viewers of UltraVNC and TightVNC allow a shared connect as a default.
    Note: If you want to enable the shared connect for a RealVNC viewer you first have to push the button Options… and then you have to click the flag Misc. By marking the option Shared Connection you are able to connect multiple RealVNC viewers from different PCs to one VNC server at the same time.
  6. Afterwards the VNC viewer asks for the VNC password which was created using the command VNCPASSWD.

    Note: If you have forgotten your VNC password you can easily create a new one by calling VNCPASSWD again. The old password is just replaced by the new one. Afterwards a restart of the VNC server is necessary to activate the new password. To stop the VNC server use the following command:
    Before you can restart the server again using STRPTL you have to logon again. STRPTL can only be called once per session.
    Note: You always can end the VNC viewer on your Windows PC without stopping the VNC server on the IBM i host or breaking any program started on IBM i. Later you can start the VNC viewer again to continue your work. It is also possible to restart the VNC viewer from a different PC. But never push the Logout of the drop-up menu of the button i5/OS. This will end the X Window manager of your VNC server and all your running programs are closed. Afterwards, you only can stop the VNC server using ENDVNCSVR.

IV. Starting SAPinst Using VNC

Note: This procedure does not work with the old SAPinst running on Windows which relies on the TMKSVR. It only works with the SAPinst running on PASE directly started on IBM i.

Prerequisite: VNC is already running as described above.

Perform the following steps to start SAPinst:

  1. If you still use the same session in which you started the VNC server you can go to step 3.
  2. Logon as the installation user (for example SAPIUSR) and set following environment variable:
          ADDENVVAR ENVVAR(DISPLAY) VALUE('<IBM i hostname>:<n>')
          (<n> is typically 1 when no other VNC server is started already)
  3. Start SAPinst without the parameter '-nogui':
          a. CD DIR('<Installation Master_DVD>/IM_OS400_PPC64')
          b. CALL PGM(QP2TERM) PARM('./sapinst')
    Note: The detailed description how to start SAPinst can be found in the installation documentation.

The SAPinstGUI appears in your VNC viewer on your Windows PC.

V. Stopping the VNC Server

After your installation or maintenance task is done you can stop the VNC server by using command: 
Note: This will also stop any VNC viewer connected to the VNC server.

VI. Starting Maintenance SAP Tools Using VNC

To start other programs than SAPinst in principle you just have to do the same steps as before. Only slide differences have to be taken into account. Especially take care that you are using the SAP system user <SID>ADM for maintenance tasks.

The following steps are the same for the SAP tools JSPM und Configtool:

  1. Prepare VNC for the IBM i user <SID>ADM as described above.
  2. If you still use the same session in which you have started the VNC server you can go to the subsections  Starting the JSPM using VNC or Starting the Configtool using VNC directly.
  3. Logon as the SAP system user <SID>ADM and set following environment variable: 
          ADDENVVAR ENVVAR(DISPLAY) VALUE('<IBM i hostname>:<n>')
          (<n> is typically 1 when no other VNC server is started already)

A. Starting the JSPM Using VNC

Depending on the SAP release the JSPM is handled differently for IBM i. The program JSPM is always started by a script file named go directly on the IBM i host. But for old releases a batch file StartGUI.bat on Windows is needed and for new releases a browser is needed to connect to the running JSPM on i. Starting the JSPM using VNC does not need a batch file StartGUI.bat or a browser started on Windows anymore:

Start the JSPM as <SID>ADM using the following two commands:
      a. CD DIR('/usr/sap/<SID>/<instance>/j2ee/JSPM')
      b. CALL PGM(QP2TERM) PARM('./go')

After some moments the GUI of the JSPM appears in your VNC viewer on your Windows PC.

B. Starting the Configtool Using VNC

The standard way for IBM i is to start the configtool on a Windows PC by double-clicking on the batch file configtool.bat in the directory \usr\sap\<SID>\<instance>\j2ee\configtool.bat. But it is also possible to start the configtool directly on IBM i using VNC:

Start the configtool as <SID>ADM using following two commands:
      a. CD DIR('/usr/sap/<SID>/<instance>/j2ee/configtool')
      b. CALL PGM(QP2TERM) PARM('./')

Now the GUI of the Configtool appears in your VNC viewer on your Windows PC.

Useful Information

Virtual Network Computing (VNC) - A free X window server running natively on IBM i.