NetRemoteExec or Net32RemoteExec

The NetRemoteExec API runs a program located on a remote server.

Restrictions

This API can be called only from an OS/2 workstation, and objnamebuf must point to a redirected resource.

Syntax

#include <netcons.h>
#include <remutil.h>
 
NetRemoteExec(reserved1, objnamebuf, objnamebufl,
         asyntraceflags, pArg, envpointer,
         returncodes, pgmPointer, reserved2,
         remexecflags);          /* 16 bit */
 
Net32RemoteExec(reserved1, objnamebuf, objnamebufl,
         asyntraceflags, pArg, envpointer,
         returncodes, pgmPointer, reserved2,
         remexecflags);          /* 32 bit */

Parameters

reserved1

(const unsigned char LSFAR *) is a reserved pointer with the value of -1.
objnamebuf
(unsigned char LSFAR *) points to the name of the object, such as a dynamic link library. The NetRemoteExec function copies a name to this buffer if it could not successfully load and start the specified program.
objnamebufl
(unsigned LSINT) specifies the size (in bytes) of the objnamebuf memory area.
asyntraceflags
(unsigned LSINT) specifies the asynchronous and trace flags. This parameter is defined as follows: ┌───────┬──────────────────────────────────────────────────────────────────────┐
│ VALUE │ MEANING │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 0 │ Synchronous process │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 1 │ Asynchronous process without result code │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 2 │ Asynchronous process with result code │
└───────┴──────────────────────────────────────────────────────────────────────┘

pArg
(const unsigned char LSFAR *) points to a set of ASCIIZ strings containing the arguments of the file to be run.
envpointer
(const unsigned char LSFAR *) points to an ASCIIZ string that is not NULL and specifies the environment for the file to be run.
returncodes
(unsigned char LSFAR *) points to an OS/2 data structure containing the return codes resulting from the file execution. This is the same data structure that is used with the OS/2 DosExecPgm function. (For more information about the return codes and the DosExecPgm function, see the OS/2 Technical Library, Programming Guide Volume 1.)
pgmPointer
(const unsigned char LSFAR *) points to an ASCIIZ string containing only the name and extension of the file to be run.
reserved2
(unsigned char LSFAR *) is a reserved pointer with the value 0.
remexecflags
(16-bit unsigned short or 32-bit unsigned long) specifies the remote executable flags that control program execution. This parameter is defined as follows: ┌───────┬────────────────────┬─────────────────────────────────────────────────┐
│ BIT │ MEANING │ SYMBOLIC CONSTANT │
├───────┼────────────────────┼─────────────────────────────────────────────────┤
│ 0 │ REM_PIPE_MODE │ If 0, a message mode pipe is used for standard │
│ │ │ input. If 1, a character mode pipe is used for │
│ │ │ standard input. │
├───────┼────────────────────┼─────────────────────────────────────────────────┤
│ 1 │ REM_WAIT_MODE │ If 0, the OS/2 DosCWait function waits for the │
│ │ │ child process to finish before returning. If │
│ │ │ 1, DosCWait waits for all spawned processes to │
│ │ │ finish before returning. │
├───────┼────────────────────┼─────────────────────────────────────────────────┤
│ 2 │ REM_SIGL_MODE │ If 0, map SIGINTR and SIGBREAK to SIGKILL when │
│ │ │ remoting standard signals. If 1, the send │
│ │ │ signals as received. │
├───────┼────────────────────┼─────────────────────────────────────────────────┤
│ 3-15 │ │ Reserved, with a value of 0. │
└───────┴────────────────────┴─────────────────────────────────────────────────┘


For more information about OS/2 signals, see the OS/2 Technical Library, Programming Guide Volume 1.

Return Codes

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) ┌─────────────────────────────┬───────┬────────────────────────────────────────┐│SYMBOLICCONSTANT │VALUE│MEANING │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_Success │ 0 │ No errors were encountered. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ ERROR_INVALID_PARAMETER │ 87 │ At least one parameter value is not │
│ │ │ valid. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_InternalError │ 2140 │ An internal error has occurred. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_RunSrvPaused │ 2385 │ The run server you requested using the │
│ │ │ NET RUN command is paused. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ErrCommRunSrv │ 2389 │ An error occurred when communicating │
│ │ │ with a run server. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ErrConnRunSrv │ 2390 │ An error occurred when connecting to a │
│ │ │ run server. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ErrorExecingGhost │ 2391 │ An error occurred when starting a │
│ │ │ background process. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_ShareNotFound │ 2392 │ The shared resource you are connected │
│ │ │ to could not be found. │
├─────────────────────────────┼───────┼────────────────────────────────────────┤
│ NERR_PgmNotFound │ 2394 │ The program was not found. │
└─────────────────────────────┴───────┴────────────────────────────────────────┘


Remarks

The NetRemoteExec function is a network extension of the OS/2 DosExecPgm function.

The executed process is run on the computer connected to the current drive of the caller. If the current drive of the caller is on a remote server, the child process is run on that server. If the current drive of the caller is a local drive, the child process is run locally.

The NetRemoteExec function requires that a remotely run process inherit one of the following handles: ┌───────┬──────────────────────────────────────────────────────────────────────┐
│ HANDLE│ MEANING │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 0 │ Standard input (stdin) │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 1 │ Standard output (stdout) │
├───────┼──────────────────────────────────────────────────────────────────────┤
│ 2 │ Standard error (stderr) │
└───────┴──────────────────────────────────────────────────────────────────────┘


When this API initiates an asynchronous process, the process identification (PID) returned as the first word in the OS/2 data structure (pointed to by the returncodes parameter) is a valid local PID that represents the remote program. The PID can be passed to the OS/2 DosFlagProcess function to:

• Send signals to the remote process
  
• Call the OS/2 DosCWait function to wait for the remote process to exit
  
• Call the OS/2 DosKillProcess function to end the process
Related Information

For information about:

• Listing resources of a server, see Share - NetShareEnum.

• Running a program, see "OS/2 DosExecPgm" in the OS/2 Technical Library, Programming Guide Volume 1.

• OS/2 DosCWait, see "OS/2 DosCWait" in the OS/2 Technical Library, Programming Guide Volume 1.

---

[Back: NetRemoteCopy or Net32RemoteCopy]
[Next: NetRemoteMove or Net32RemoteMove]