RUNJB

Issue a system command or start a concurrent process

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

xcall RUNJB(program, [terminal], [pid], [subprocess][, io_flag])

Arguments

program

The file specification of the executable file to be run. (a)

terminal

(optional) A field that contains the device name or number of the terminal to be attached to the process. A negative value (-1) causes the job to be run as a detached process. Terminal is ignored on Windows and UNIX. (a or n)

pid

(optional) Returned with the process ID of the child or subprocess that runs concurrently with the initiating process. (n)

subprocess

(optional) A flag that determines what type of process is created: (n)

1 = A subprocess is created.

0 = A detached process is created.

Subprocess overrides system option #35 if it is present. It is not allowed on Windows or UNIX.

io_flag

(optional) Determines how SYS$INPUT, SYS$OUTPUT, and SYS$ERROR are set up when a process is created and also determines how that process is started. It can have the following values: (n)

0 = The following are true:

• SYS$INPUT is a mailbox.
• SYS$OUTPUT is _NLA0: if terminal is less than zero; otherwise, it is the device.
• SYS$ERROR is null.
• The image for the created process is SYS$SYSTEM:LOGINOUT.EXE.
• The following commands are written to the mailbox: $ RUN program, $ LOGOUT
• The mailbox channel is then deassigned.
• DBL$RUNJB_OUTPUT is an optional logical assignment of an output device.

nonzero = The following are true:

• SYS$INPUT, SYS$OUTPUT, and SYS$ERROR are all set to _NLA0: if terminal is less than zero; otherwise they are the terminal device.
• System option #35 is ignored.
• The image for the created process is the program name that is passed.

Io_flag is not allowed on Windows or UNIX.

Discussion

RUNJB on Windows

The RUNJB subroutine starts another process to run concurrently with the process that initiated it. All programs are run as background processes and should not be made to interact with the terminal.

If program is a Synergy program, the dbr command is not necessary. (For example, “dbr myjob” can just be “myjob”.) Program cannot contain an environment variable, as in “DBLDIR:lpque.bat”. You must translate the environment variable using the GETLOG routine, unless lpque is a Synergy program. If RUNJB is used to execute a batch file, the command interpreter start keyword must precede the batch file (for example, “cmd.exe /c start c:\mybatch.bat”).

RUNJB on UNIX

The RUNJB subroutine starts another process to run concurrently with the process that initiated it. The STTY subroutine can be used to modify the terminal settings if the new program changes the terminal settings. All programs are run as background processes, so they should not be made to interact with the terminal.

If you try to run more than the maximum number of processes (which is determined by the configuration of your UNIX kernel and varies from system to system), you’ll get a “Too many processes” error ($ERR_MAXPRC).

If program is a Synergy program, it is not necessary to include the dbr command. (In other words, “dbr myjob” can just be “myjob”.) Program cannot contain an environment variable, as in “DBLDIR:lpque”. You must translate the environment variable using the GETLOG subroutine, unless lpque is a Synergy program.

When RUNJB is performed, the UNIX exec command creates a duplicate process which then closes channels that are open. If you have not flushed data for a file opened for output, the data may be duplicated due to the deferred flush of cached write data.

RUNJB on OpenVMS

The RUNJB subroutine enables a Synergy program to start up an OpenVMS subprocess that is to execute concurrently with the initiating process. The subprocess continues to execute until either the parent process is terminated (for example, with a LOGOFF or the KILL subroutine) or the subprocess terminates itself. The subprocess has a base priority of four.

If you want a Synergy program to initiate a subprocess and wait for its completion before continuing execution, use the VMCMD or SPAWN subroutines.

If system option #35 is set, the created process is detached, unless this setting is overridden by a subprocess value of 1. Initiating a subprocess on another terminal requires both the DETACH privilege and that the terminal not be logged into the system or otherwise allocated.

Because RUNJB requires the command line interpreter, if you are using xfServerPlus, you cannot XCALL this routine from within a shared image unless it creates another detached process, in which case it may be used.

If the terminal argument is numeric, it is translated into its corresponding terminal device name. If this argument is not passed, the calling program’s internal TNMBR value is used.

Examples

The example below reads the name of a program that is to be run concurrently as a separate process on UNIX or OpenVMS.

.define TTCHN           ,15
record
    program             ,a64
    tty                 ,d3
proc
    open(TTCHN, o, "tt:")
    display(TTCHN, "Which program do you want to run in background?")
    reads(TTCHN, program, done)
    tty = 0                             ;Terminal # ignored on UNIX
    onerror ($ERR_MAXPRC)nope, oops
    xcall runjb(program, tty) ;Start program
    offerror
    display(TTCHN, program, "has been started in background")
    forms(TTCHN, 1)
    close(TTCHN)
    stop
nope,
    writes(TTCHN, "Too many processes")
    goto done
oops,
    display(TTCHN, "Cannot execute: ", program)
    forms(TTCHN, 1)
    goto done
done,
    stop
end