SYS( ) Invoke Operating System Command

System Functions

SYS( )

Invoke Operating System Command

1. Invoke Operating System Command: SYS(command$[,ERR=stmtref])
2. Signal Another Process (PVX UNIX/Linux Only): SYS(pid[,signal][,ERR=stmtref])

Where:

command$	Command to be processed. Maximum string size 8kb.
pid	UNIX/Windows Process ID value to check/notify. Numeric expression.
signal	Optional signal value to send to the UNIX Process ID. Numeric expression.
stmtref	Program line number or statement label to which to transfer control.

Returns

Operating system code identifying command passed to it by the function.

Description

The SYS( ) function passes a given string or numeric Process ID to the operating system command processor for execution.

Format 1

Invoke Operating System Command

SYS(command$[,ERR=stmtref])

SYS( ) returns the operating system's code identifying the command. It returns zero if the task is running and not zero (usually -1) if it is unsuccessful. The value in the system variable RET can be checked for an error value if the function was unsuccessful.

Example:

0010 PRINT 'CS',"Menu"
0020 PRINT " 1: List directory"
0030 PRINT " 2: Run WORD processor"
0040 PRINT " 3: Run SPREADSHEET"
0050 PRINT " X: Sign off"
0060 INPUT "Enter selection:",X$
0070 IF X$="1" THEN LET X$="ls"; GOTO 0500
0080 IF X$="2" THEN LET X$="wp"; GOTO 0500
0090 IF X$="3" THEN LET X$="123"; GOTO 0500
0100 IF X$="X" THEN QUIT
0110 PRINT 'RB',; GOTO 0060
0500 A=SYS(X$)
0510 IF A<>0 THEN PRINT "Command '"+X$+"' FAILED"
0520 GOTO 0020

Format 2

Signal/Terminate Another Process (ProvideX UNIX/Linux Only, PxPlus all platforms)

SYS(pid[,signal][,ERR=stmtref])

The SYS function can be used to determine the state or interupt/terminate another process on the system. If the signal is omitted or set to zero the SYS function will return zero if the specified process is still executing, or -1 if the process cannot be found (terminated).

On Windows (PxPlus only) the SYS function can only be used to get the status of or terminate a process with the terminate status given in signal.

On Unix/Linux the SYS function can be used to send a signal to another process which may cause the other process to terminate depending on the signal chosen. Sending a signal 2 (SIGBREAK) from a session or from the UNIX shell will initiates a program's SETESC logic. Sending a signal 15 requests that the processs shutdown. Signal 9 is a forced termination request.

For Example, on Unix, to send a ESCAPE/Break to the process whose id is in pid:

X=SYS(pid,2)

The first argument is the PID signal to send and the second is the signal number.

To obtain the pid for the current process use TCB(89) which returns the numeric value of the current Process ID.

On Windows a special pid value of -1 can be specified to check the state of the process initiated by the last SYSTEM_HELP directive.