WindX™ Thin-Client

*WindX.utl

WindX Utility Program

The WindX utility program, *WindX.utl, provides a variety of functions that simplify the development of applications that make use of WindX.

Format

Format of the CALL:

CALL "[WDX]*WindX.utl;function",params

Use this format to call the utilities/functions in the WindX.utl utility program.

Example:

CALL "[WDX]*WindX.utl;GET_LWD",Station_dir$
CALL "*WindX.utl;SPAWN",cmdline$,inifile$,appfid$

Functions

The following functions are built into WindX to simplify development tasks:

CALL "[WDX]*WindX.utl;CWDIR",dir$

Changes to the specified directory on the WindX client.

CALL "[WDX]*WindX.utl;GET_ADDR",X$

Returns the IP address of the WindX client.

Note:
For SSH WindX connection, this does not return the IP address of the client, but rather the plink command used on the client to connect to the SSH server.

To get the SSH client IP address, use the ENV function to return the IP address. The function must be run on the server, not the client; i.e. do not use [WDX]/[LCL].

CALL "[WDX]*WindX.utl;GET_ARG",X,Y$

Returns the command line argument number specified by X in Y$.

CALL "[WDX]*WindX.utl;GET_DIR",X,Y$

Returns the DIR( ) information for the directory specified by X (or X$) in Y$.

CALL "[WDX]*WindX.utl;GET_DSK",X,Y$

Returns the DSK( ) information for the disk specified by X (or X$) in Y$.

CALL "[WDX]*WindX.utl;GET_FILE_BOX",path$,dir$,title$,ex_list$,def_ex$

CALL "[WDX]*WindX.utl;GET_FILE_BOX_DIRECTORY",path$,dir$,title$,root$

CALL "[WDX]*WindX.utl;GET_FILE_BOX_READ",path$,dir$,title$,ex_list$,def_ex$

CALL "[WDX]*WindX.utl;GET_FILE_BOX_WRITE",path$,dir$,title$,ex_list$,def_ex$

CALL "[WDX]*WindX.utl;GET_FILE_BOX_READ_LIST",path$,dir$,title$,ex_list$,def_ex$

(Support for GET_FILE_BOX_READ_LIST was added in PxPlus 2017.)

Emulates a local call to GET_FILE_BOX directly on the WindX client. The parameters are:

path$

String variable that contains the file path.

dir$

Initial directory to display. String expression.

title$

Window title. String expression. If not specified, the defaults for the various formats will be used.

ex_list$

List of standard file extensions (e.g. .jpg, .pdf, .txt, etc.). Comma or your choice of character as the delimiter (the last extension must end with the delimiter). Optional. String expression. Use the format Description|*.XXX, as in the following example:

Example:

"Applications|*.EXE,Text|*.TXT,PDFs|*.PDF,All|*.*,"

Note:
If defining only one file type, a delimiter (i.e. comma) must be added to the end. PxPlus uses this last character as the delimiter.

def_ex$

Default file extension to use if no file extension is specified via the file extension drop box or the file path input field. Optional. String expression.

Example:

"TXT"

root$

Optional highest level directory in which browsing can occur. (This parameter overrides dir$.)

CALL "[WDX]*WindX.utl;GET_LPG",X$

Returns the LPG (Lead Program Name) system value for the WindX session.

CALL "[WDX]*WindX.utl;GET_LWD",X$

Returns the current LWD (Local Working Directory) for the WindX session.

CALL "[WDX]*WindX.utl;GET_NEWPORT",X

Returns the port number of an unused TCP/IP port on the WindX station.

CALL "[WDX]*WindX.utl;GET_NUM",X$,Y

Evaluates/returns the value of the numeric expression X$ in Y.

Example:

Y=EVN(X$)

CALL "[WDX]*WindX.utl;GET_TCB",X

Returns the value of the TCB function task specified by X in X.

Example:

X=TCB(X)

CALL "[WDX]*WindX.utl;GET_VAL",X$,Y$

Evaluates/returns the value of the string expression X$ in Y$.

Example:

Y$=EVS(X$)

CALL "[WDX]*WindX.utl;GET_WINDX",X$

Returns the absolute pathname of the WindX program.

CALL "*WindX.utl;SPAWN",X$,I$,F$,HideClient,HideServer

(See Notes below)

Spawns a new session of PxPlus on the host and an associated WindX session on the client PC. By default, if the main session terminates, then the spawned session terminates.

The parameters are:

X$

Command line parameters to be used on the host.

I$

Pathname of the INI file to be used on the client PC.

F$

Value of FID(0) for the session.

HideClient

An optional parameter that is provided, and non-zero indicates that the spawned WindX session is to start hidden.

HideServer

An optional parameter that is provided, and non-zero indicates that the spawned host session is to start hidden as opposed to being started minimized (only applicable to Windows servers).

CALL "*WindX.utl;SPAWN_NOHUP",X$,I$,F$,HideClient,HideServer

(See Notes below)

Same as SPAWN but detaches the session from the main user task. If the main task terminates, then the spawned task continues executing.

 

Notes:
The CALL to *WindX.utl;SPAWN and *WindX.utl;SPAWN_NOHUP should not have the [WDX] prefix in front, as they are performed locally. The spawn interface uses the value found in the global variables %PXPLUS_HOST$ and %APS to determine how to spawn the new process.

If %APS is set, it is assumed to contain the object handle to the Application Server client object module, and the spawn logic will use it to spawn the new process.

If %PXPLUS_HOST$ is set, it is used to define the host name/IP address and port number to use when spawning a task.
     •  If the first character is an * asterisk, the system will internally spawn the new process and use the host and port number to connect to it.
     •  If the first character is not an * asterisk, the system will assume you are running *plus/cs/host on the host/port specified and spawn a process to connect to this host process.
     •  If neither of the above is defined, the system will attempt to spawn a new process locally and connect using a random port number.

How to Spawn a Process When Using WindX and SSH

Because SSH effectively requires a user to log on to the UNIX/Linux system, spawning a session when you are connected using SSH requires some special settings. This would also be required when using the report viewer *VIEWER* as it spawns a process.

Basically, you have two options, both of which are controlled by setting the global variable %PXPLUS_HOST$ prior calling *WindX.utl;SPAWN.

One option is that you can run *plus/cs/host in the background on your server and set %PXPLUS_HOST$ to your server's IP address, followed by a ; (semi-colon) and the port number (e.g. "192.168.1.123;4093"). This will cause *WindX.utl to connect to the CS host, have it spawn a task, and then connect to it.

Note:
The spawned task will run under whatever UserID *plus/cs/host was launched.

The other option is that you can set %PXPLUS_HOST$ to an * (asterisk), followed by the same host address, a ; (semi-colon) and the port number. In this case, you do not need to run *plus/cs//host, as your application itself will spawn the process and connect to it. This will preserve the UserID and other environmental settings in the spawned process.

The challenge is to make sure that the host address you use is the host address as seen by the workstation. For example, if your host server is connected to the Internet using a router, and the workstation will be coming in from outside, then the IP address will need to be the external address and not internal address.

Note:
In both cases, you will need to make sure that the port you use is accessible from the workstation and is not blocked by a firewall.