J3/05-240r3

To: J3
From: Dan Nagle
Subject: Execute an external program
Date: 2005 August 9

Specifications of J3-003

  Executes a command line externally to the program.
  Whether the command line is interpreted by a shell
  is unspecified.  Require synchronous execution and
  allow asynchronous execution.  If synchronous execution,
  allow recovery of the executed process exit status.
  Allow processor-dependent error conditions.

Syntax:
add the intrinsic

EXECUTE_COMMAND_LINE( COMMAND , WAIT, EXITSTAT, CMDSTAT, CMDMSG )

Edits:

In Section 13.5.8, page 298, add to the list:

[298:5+] Add:
"EXECUTE_COMMAND_LINE      execute a command line"

In Section 13.7, add to the list of procedures:

[315:24+] Add:
 "13.7.5+ EXECUTE_COMMAND_LINE( COMMAND [, WAIT,
                                          EXITSTAT, CMDSTAT, CMDMSG ] )

*Description.* Execute the command line specified
               by the string COMMAND.  If the processor supports
               command line execution, it shall support
               synchronous and may support asynchronous execution
               of the command line.

*Class.* Subroutine.

*Arguments.*

COMMAND    shall be of type default character and
           shall be a scalar.  It is an INTENT(IN)
           argument.  Its value is the command line
           to be executed.  The interpretation is
           processor-dependent.

WAIT       shall be of type default logical and shall
(optional) be a scalar.  It is an INTENT(IN) argument.

EXITSTAT   shall be of type default integer and shall
(optional) be a scalar.  It is an INTENT(INOUT) argument.

CMDSTAT    shall be of type default integer and shall
(optional) be a scalar.  It is an INTENT(OUT) argument.

CMDMSG     shall be of type default character and shall
(optional) be a scalar.  It is an INTENT(INOUT) argument.

When WAIT is present and has the value true, EXECUTE_COMMAND_LINE
returns after the command line
has completed execution.  When WAIT is present and has the value
false, and the processor supports asynchronous execution
of the external command, EXECUTE_COMMAND_LINE returns without
waiting.  In all other cases,
the effect is as if WAIT were present with a value true.

If WAIT has the value true, the value of
EXITSTAT is the processor-dependent exit
status of the command line execution, if available.
Otherwise, the value of EXITSTAT is unchanged.

CMDSTAT is assigned the value zero if
no error occurred during EXECUTE_COMMAND_LINE
and is assigned a processor-dependent
positive value otherwise.  If an error occurs
and CMDSTAT is not present, execution of
the program terminates.  If the processor
does not support the concept of command line execution,
CMDSTAT is assigned the value 1.

If an error occurs and CMDSTAT and CMDMSG are present,
a processor-dependent error message is assigned to CMDMSG.
Otherwise, the value of CMDMSG is unchanged."