Special Command Tags

Formats

Where:

Note:
This feature requires WindX activation.

Description

The [WDX] tag is used as a prefix to perform an action on a remote client machine (if your given command could be used on either client or server, and if the command supports using [WDX]). The [WDX] tag can only be used in specialty commands when running under WindX.

WindX supports the use of the following directives via the [WDX] tag: SERIAL, KEYED, DIRECT, SORT, PROGRAM, DIRECTORY, REFILE, ERASE, EXECUTE, INVOKE, OPEN, CALL, DEF OBJECT and INDEXED, as well as the use of the NEW function. The use of the [WDX] tag is also supported in Format 2 of the PTH( ) function.

Note:
The DIR= option and the PURGE and FILE directives are not supported by WindX and must be encapsulated in an EXECUTE directive.

To Detect WindX

To detect whether or not you are actually working on a WindX PC in Command mode, look for the special prompt -} ... i.e. a hyphen with a curly brace. In your applications, a test for one of the following indicators will tell you that your session is running under WindX:

DEC(MID(MSE, 22,1))>0
TCB(88)<>0

See TCB( ) function and MSE system variable.

You can create a global variable in your WindX setup and use it later to test for the presence of a WindX client PC connection. Then, if WindX is running the session, you can use the [WDX] tag.

Example:

In this example, the user-defined variable %WDX is only set when WindX is running; otherwise, its value is null:

if mid(mse,22,1)>$00$ and mid(mse,22,1)<$FF$ \
     then %WDX$="[WDX]"

Use such a global variable in a statement like OPEN (30)%WDX$+"*WINPRT*" to bypass an Error #12: File does not exist (or already exists) when WindX is not running.

Note:
WindX will support all the directives and functions that are used against a file channel that was previously opened with a [WDX] or [LCL] tag.

How PxPlus Detects WindX 

PxPlus uses terminal type to detect a WindX session. In UNIX, PxPlus recognizes two terminal types as potential WindX stations (TERM="winterm" for the WindX client PC and TERM="ansi"). Since most UNIX systems and applications cannot recognize or use the winterm type, the PxPlus ansi device driver sends a special escape sequence to a terminal to test for a WindX client. If the terminal is a WindX PC, a special response is generated. If no response is generated before a time-out occurs, PxPlus assumes that the device is ansi.

GUI Requests

Once the PxPlus session on the server recognizes the terminal as a WindX station, it changes the internal settings to allow graphical requests to be routed correctly. (Then, graphical requests are automatically tokenized and forwarded to WindX for processing; that is, you do not need the [WDX] tag.)

For instance, a server command to print a picture in a UNIX environment would automatically be sent to WindX for the client. PxPlus transmits standard mnemonics to WindX as an escape ($1B$) followed by the mnemonic in native form. Traffic from the host/server is minimized because the WindX client's PxPlus interpreter handles a lot of the functionality locally (on the client) for screen refreshing and graphical requests.

In WindX, your instruction to print is sent to the client, bundled as is. When you use mnemonics and/or graphics, such as .bmp, they must exist on the client or be accessible to the client.

Example:

This example uses a 'PICTURE' that is defined and shared on a common Windows server instead of being stored on each individual client machine:

print 'picture'(10,10,10,10),"\\serv_name\driveshare\your_bmps\that.bmp"

Formats 1 and 2

Initiate Remote Command

EXECUTE "[WDX]statement"
INVOKE "[WDX]statement"

Use the EXECUTE and INVOKE formats with the [WDX] tag to process commands on the WindX PC (remote client). Common applications of the EXECUTE format would be changing the client's local directory, setting system parameters, or altering the prefix and in file creation.

Warning!
When you use the EXECUTE and INVOKE directives from your server to initiate action remotely on a client, the client PC might be running a PxPlus activation with a different set of syntax tables. As a result, your MNEMONICs might be invalid.

Example:

This example illustrates the use of an EXECUTE "[WDX]statement" in an application on the host/server to define a MNEMONIC directive locally on the WindX client:

if WDX%<>$00$
     then execute "[WDX]mnemonic(lfo)'5X'=$1B+hex$"
     else goto MY_LABEL

This next example sets the 'B0' system parameter on a WindX PC using a [WDX] command from a UNIX host:

execute "[WDX]SET_PARAM 'B0'"

Note:
If you run your application with 'B0' set, make sure that it is set on both the host and the WindX PC; otherwise, the wrong windows will be addressed. (You can set 'B0' either by executing it from the host, as in the example, or by using -B0 as an argument on the WindX PC's Start_up Command line.)

Format 3

Call Subprogram

CALL "[WDX]subprog",params

This format enables the server to CALL a subprogram that exists and runs remotely on the client. It is true distributed processing. The server's files and global variables are not accessible to your subprogram. Your remote call passes parameters back and forth, not data files. You can pass a maximum of 20 parameters/arguments in a comma-separated list.

Example:

You can call applications such as special printer device drivers you have built on the client to handle print mnemonics:

CALL "[WDX]*dev/your_driver_name"

You can use a similar format to call the PxPlus *WindX.utl (utility) functions. See Format 10: [WDX] and *WindX.utl.

Formats 4 and 5

Open Files, Serial Ports on Client

OPEN (chan[,fileopt])"[WDX]filename"
OPEN (chan,OPT=settings$)"[WDX]port_id"

Use this format in programs running on your server when you are opening remote files or ports; that is, using [WDX] as a prefix to the pathname of your file (or port, etc.) tells WindX to open it remotely on the client. WindX automatically forwards requests (i.e. file I/O directives) for processing.

Note:
When you need a statement that is not supported on a WindX PC, encapsulate your commands in an EXECUTE "[WDX]..." directive or design your applications to run remotely on the client.

Example:

The following example opens a remote file:

open (1)"[WDX]CLIENT_PATH\CLIENT_FILE"

Use a similar format to open a COM port for direct access to a serial device (e.g. a serial printer or weigh scale) on the client PC without going through a spooler:

SETTING$="9600,n,8,1,x"
open (5,opt=SETTING$)"[WDX]COM2"

or 

open (5,opt="9600,n,8,1,x",err=OOPS)"[WDX]COM2"

Format 6

[WDX] with Other Tags

OPEN (chan[,fileopt])"[WDX][tag]prog;[params]"

[WDX] can be used in conjunction with other file tags.

Example:

open (1)"[WDX][DDE]excel;existing_worksheet.wk1"

Format 7

Windows Print Subsystem on Client 

OPEN [INPUT] (chan[,fileopt])"[WDX]*device*[;Q_name[;Q_options]]"

PxPlus opens the special device files *WINPRT* and *WINDEV* on the PC/server that issues the command. Except in UNIX (where it is done automatically), use [WDX] with OPEN [INPUT] directives for the two specialty files to direct any print jobs and dialogues to the WindX client PC, which will in turn use its Windows print subsystem API to deal with the jobs and send them to the given printer.

Example:

open (7,err=1500)"[WDX]*WINPRT*"

With a WindX client and an NT Server, if you do not use [WDX] in your OPEN directive, then the printer selection dialogue will appear on the server console, and any print queue you name directly must exist on the NT server in the Control Panel, Printers folder.

See *WINDEV* Raw Print Mode and *WINPRT* Windows Printing.

Formats 8 and 9

Remote Object Support

NEW("[WDX]ClassName")
DEF OBJECT com_id,"[WDX]objname"

The [WDX] tag can be used to create OOP/COM objects and manipulate them across a WindX connection as if they existed locally.

Methods can be passed arguments and receive results; however, only the result of a method will be returned across a remote connection. Any changes to the arguments of a method by the remote object will not be returned across the connection. Arguments are therefore considered to be passed by value only. If you need to retrieve arguments as well as the result, you must place your code in a program on the WindX workstation and interact with that code.

Event handling is not supported across a remote connection. Event mapping must occur within the remote object. The remote object will not have access to any server resources. At most, the remote event could pass a CTL back to the local server for action. It is recommended that objects requiring event processing exist completely on the remote and interact only with the local WindX session on the remote.

Format 10

[WDX] and *WindX.utl

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

Use this format to call the utilities/functions in the WindX.utl utility program. See *WindX.utl Utility Program.

Example:

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

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

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.

See Also

*WindX.utl Utility Program