`phrelay`

Support remote connectivity with phindows and phditto clients

Syntax:

phrelay [-b number -V... -D debugfile -X]

Options:

-b number: Set the number of messages buffered to allow write-ahead draws to Phindows or phditto. The actual number used is the lesser of this option and the -N option of Phindows or phditto. The default value is 20. Use a lower value to save memory at the expense of throughput, or, if memory is not an issue, a higher value to gain some additional throughput performance. Adjusting this setting has the most effect when end-to-end response time is slow compared with throughput, such as over a modem or when there are many network hops between the local and remote ends.
-D debugfile: The file or device to which to send the debugging information specified by the -V option.
-V...: Be verbose. Add more V's for greater verbosity. Output is sent to the file or device you specify in the -D option that's required if you specify -V.
-X: Embed color palette information into the data stream. This option works around a problem where some applications with many small graphics may have incorrect palette tags, and therefore are displayed incorrectly on the client screen. If small graphics (such as on buttons) appear correctly, you do not need to use this option.

Description:

The phrelay utility supports remote user interface clients on other nodes.

When you specify a modem (using the -m option to phditto or phindows), the remote client first acts as a simple text terminal emulator so you can interact with the modem, dial up a remote QNX machine, and log in.

Once you're logged in, you can start a Photon session by entering the following command:

exec /usr/bin/phrelay

The remote client synchronizes with phrelay and starts to function as a Photon graphics terminal.

Remote connectivity via TCP/IP

When you specify a TCP/IP connection (using the -t option to phditto or phindows), the inetd program running on the remote QNX host automatically launches phrelay for you, provided phrelay and inetd have been configured properly (see below).

Configuring for TCP/IP

There are several configuration issues that need to be taken care of before you can use phrelay over TCP/IP.

First, the QNX host must have TCP/IP installed and running. In addition, inetd must be running with the following items specified in the inetd configuration file /etc/inetd.conf:

phrelay stream tcp nowait root /usr/bin/phrelay phrelay

The file /etc/services file must include the following line (it's in the default file):

phrelay 4868/tcp

These two entries cause inetd to listen for incoming requests to establish a new Photon session. When a request is detected (from a remote phindows or phditto client), inetd automatically establishes a full TCP/IP connection and launch phrelay on that connection. The remote phindows or phditto client is then fully connected to a local Photon session.

Using predefined Photon services

The -s command-line option of phditto and phindows is provided to simplify the task of creating shortcuts to Photon applications within the MS-Windows desktop.

By using the -s option, you can create an icon or shortcut on the MS-Windows desktop to start up a Photon application automatically (within a private phindows session). With proper specification of the remote Window Manager options, it's possible to make that Photon application look like it's a native MS-Windows application.

When phrelay runs on the QNX host machine, it looks up the Photon service specified with the -s parameter in a configuration file (/etc/config/phrelay[.node]). If a matching service is found, then phrelay launches the specified Photon command instead of the default Photon desktop. You can specify optional window-manager options, but the default mode is to start the remote Photon application so that it looks and behaves as if it were a native MS-Windows application.

The phditto/phindows -U option is often used with the -s option to specify a QNX userid to use when running the remote Photon command. If no userid is given, and the phrelay service doesn't specify a default userid, then Photon pops up the QNX Photon Login dialog requesting the QNX userid before proceeding. By specifying a userid with the -U option, you can avoid this login dialog.

For example, if a MS-Windows shortcut were created as follows:

phindows -tx.x.x.x -svpoker -Ujoe

where the IP address x.x.x.x specified the TCP/IP address of QNX node 2, and the phrelay configuration file on node 2 (/etc/config/phrelay.2) contained the following line:

vpoker % /usr/photon/bin/vpoker

then Joe could directly launch a Photon vpoker session (running as QNX userid joe) on his MS-Windows desktop by clicking on the shortcut icon.

`phrelay` configuration file format

The phrelay utility processes requests for service according to the contents of a configuration file. If phrelay is running on QNX node n, then the file /etc/config/phrelay.n is used. If this file doesn't exist, then the default file /etc/config/phrelay is used.

The format of each service entry in the phrelay configuration file is as follows:

service user [-W pwm_options] command

where:

service is the symbolic name of the Photon service (matches the -s phindows or phditto parameter).

user defines how to process userids that may be specified on the phindows or phditto command line (-U option).

user can be one of:

userid: QNX userid (if no -U). Prompt for password if required.
userid:password: QNX userid and password (if no -U).
%: Prompt for user/password (if no -U).
?: Always prompt for user/password (ignore -U).
!: Fail (if no -U).
=userid: Force this userid (ignore -U).
=userid:password: Force this userid and password (ignore -U).

pwm_options can be one or more of the following Photon Window Manager options:

P

Disable Taskbar, console switching, and keyboard.

W

Disable Workspace menu.

R remote_option

Remote Window Manager options, where remote_option can be one or more of:

b: Remove Photon Window Manager borders.
c: Close Window Manager when program terminates.
f: Fit. Make application always fit in phditto/phindows window).
m: Initially resize application to fit in phditto/phindows window.
r: Initially resize phditto/phindows window to fit application.
t: Send Window title to phditto/phindows.

The default Window Manager options are PWRcbtfr.

command is the Photon command to launch instead of the default command, which starts the Photon desktop.

Data compression options

The phrelay utility supports one of three data compression options that the client can request:

Byte-Pair Encoding -- (BPE) performs the best data compression and is recommended for all serial connections. Although BPE is inexpensive to decode (both in memory and CPU usage), it does require a fair amount of CPU on the host QNX machine. When link speeds are low (such as with modem links), the extra cost in CPU on the sending side is well worth the tradeoff.
Run Length Limited -- (RLL) provides good data compression. Although not as highly compressed as BPE, RLL encoding is both quick to decode and encode. RLL encoding is recommended for network TCP/IP connections because it places less CPU load on the QNX host, yet provides fair compression.
None -- With data compression turned off, Photon draw events are transmitted "as is." This might make sense if the connection bandwidth is very high (say 100Mb Ethernet), making the extra processing time involved in data compression an unnecessary step.

Data caching options

The phrelay utility makes very extensive use of data caching techniques to minimize the amount of data that needs to be transmitted from the host to the client machine. Thanks to this intensive data caching, phditto/phindows can operate over modem-link speeds as low as 9600 baud.

Most "large" static data objects in Photon are "tagged" with a unique 32-bit ID (tag). Tagged objects include bitmap data, image data, and color palettes. These objects are generally tagged when first created by the Photon program developers. This process is accomplished automatically by the Photon development tools, so the program developer is, for the most part, not even aware that this is taking place.

Photon passes these tags along with the data objects as they flow through the Photon event space. The end result is that Photon graphics drivers (such as phrelay) almost always have available a small, unique, precalculated tag to identify the larger Photon graphical objects.

Draw buffer limits

Because phrelay renders fonts locally as bitmaps, large amounts of text can cause large draw buffers. In some extreme cases, if the draw buffer size is exceeded, the phditto or Phindows window displays the error "[Error: Large Draw Buffers]", and the draw buffer is discarded. For example, scrolling large amounts of text in a pterm window that spans four virtual consoles will cause this error.

The phrelay draw buffer has a size limit of 256kb of pixels (or about 21,000 characters in the default 12 point PC Serif font in pterm). You can use the Windows font rendering option in Phindows to have Phindows rather than phrelay render the fonts and thereby reduce the draw buffer size for text significantly. For more information see Using Windows fonts in the Phindows Users Guide.

Examples:

From a remote phindows or phditto session, type:

exec /usr/bin/phrelay

QNX Developer Support