Special Command Tags

[WDX]

Direct Action to Client Machine

Formats

 1. Execute:

EXECUTE "[WDX]statement"

 2. Invoke:

INVOKE "[WDX]statement"

 3. Call Subprogram:

CALL "[WDX]subprog",params

 4. Open File:

OPEN (chan[,fileopt])"[WDX]filename"

 5. Open COM Port:

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

 6. Open Tag Process:

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

 7. Open Print Devices:

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

 8. Create Object:

NEW("[WDX]ClassName")

 9. Define Windows Object:

DEF OBJECT com_id,"[WDX]objname"

10. Call *WindX.utl:

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

Where:

 

[WDX]

File tag notifies PxPlus that you are directing the action to the WindX client machine instead of the server.

 

chan

Channel or logical file number to open.

 

class$

Name of class for creating new object. String expression.

 

com_id

Numeric variable to receive a handle (memory pointer to object).

 

*device*
Q_name
Q_options

Identifier and parameters for either of the two [WDX]-supported special device files (*WINDEV* or *WINPRT*). See *WINDEV* Raw Print Mode and *WINPRT* Windows Printing.

filename

Name of the file to open (file must exist on the client PC).

Example:

   open (14)"[WDX]"+TMP$  or
   open (14)"[WDX]temp_file"

 

function

A PxPlus utility/function, part of the *WindX.utl utility program. See *WindX.utl Utility Program. For instance, the *WindX.utl;SPAWN function initiates tasks on the server and/or client.

 

fileopt

File options. Supported options include:

ERR=stmtref

Error transfer

IOL=iolref

Default IOList

ISZ=num

Open file in binary mode

OPT=char$

File open options

REC=string$

Record prefix (REC=VIS(string$) can also be used)

 

objname$

Name by which the COM object is registered in the Windows system registry subkey HKEY_CLASSES_ROOT.

 

params

Arguments and variables you pass to the subprogram or function. If you include a list, it is comma-separated.

 

port_id

System identifier for the port (e.g. COM1).

 

prog;function

Parameters for the [tag].

Example:

For [DDE] to export to Excel, you can open a worksheet using either:

   "[WDX][DDE]EXCEL;existing_worksheet.WK1"

    or

   "[WDX][DDE]EXCEL;"

In the first example, where a spreadsheet name is included, it must exist on the client PC.

 

tag

PxPlus special command file tag. (All are listed in this section.)

Example:

   [DDE], [DLL], etc.

 

settings$

Serial device's attributes (baud rate, etc.). String expression.

 

statement

Command supported by PxPlus (some are not) for use with EXECUTE or INVOKE + the [WDX] tag in WindX. String expression.

 

subprog

Subprogram for the CALL directive.

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:

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.

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.

See Also

*WindX.utl Utility Program