const type: popenFile

File implementation type for operating system pipes.

const type: popen8File

File implementation type for UTF-8 encoded operating system pipes.

const func integer: shell (in string: command, in string: parameters)

Use the shell to execute a command with parameters. Parameters which contain a space must be enclosed in double quotes (E.g.: shell("aCommand", "\"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

Returns:

the return code of the executed command or of the shell.

const proc: shellCmd (in string: command, in string: parameters)

Use the shell to execute a command with parameters. Parameters which contain a space must be enclosed in double quotes (E.g.: shellCmd("aCommand", "\"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the shellCmd function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shellCmd function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

Raises:

FILE_ERROR - The shell command returns an error.

const func integer: shell (in string: cmdAndParams)

Executes a command using the shell of the operating system. The command path must use the standard path representation. Spaces in the command must be preceded by a backslash (E.g.: shell("do\\ it"); ). Alternatively the command can be enclosed in double quotes (E.g.: shell("\"do it\""); ). Command parameters containing a space must be enclosed in double quotes (E.g.: shell("do_it \"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the shell function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shell function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

Returns:

the return code of the executed command or of the shell.

const proc: shellCmd (in string: cmdAndParams)

Executes a command using the shell of the operating system. The command path must use the standard path representation. Spaces in the command must be preceded by a backslash (E.g.: shellCmd("do\\ it"); ). Alternatively the command can be enclosed in double quotes (E.g.: shellCmd("\"do it\""); ). Command parameters containing a space must be enclosed in double quotes (E.g.: shellCmd("do_it \"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the shellCmd function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the shellCmd function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

Raises:

FILE_ERROR - The shell command returns an error.

const func string: shellEscape (in string: stri)

Convert a string, such that it can be used as shell parameter. The function adds escape characters or quotations to a string. The result is useable as parameter for the functions shell, shellCmd, popen and popen8. Shell parameters must be escaped individually. Afterwards escaped parameters are joined to a space separated list of parameters.

Returns:

a string which can be used as shell parameter.

Raises:

MEMORY_ERROR - Not enough memory to convert 'stri'.

const func string: toOsPath (in string: standardPath)

Convert a standard path to the path of the operating system. The result must be escaped with shellEscape to be useable as parameter for the functions shell, shellCmd, popen and popen8.

Parameters:

standardPath - Path in the standard path representation.

Returns:

a string containing an operating system path.

Raises:

MEMORY_ERROR - Not enough memory to convert standardPath.

RANGE_ERROR - standardPath is not representable as operating system path.

const func string: toShellPath (in string: path)

Convert a standard path such that it can be used as shell parameter. The result is useable as parameter for the functions shell, shellCmd, popen and popen8. Shell parameters must be converted individually. Afterwards converted parameters are joined to a space separated list of parameters.

Parameters:

standardPath - Path in the standard path representation.

Returns:

a string containing an escaped operating system path.

Raises:

MEMORY_ERROR - Not enough memory to convert standardPath.

RANGE_ERROR - standardPath is not representable as operating system path.

const func file: popen (in string: command, in string: parameters, in string: mode)

Open a pipe to a shell command with parameters. The command reads, respectively writes with Latin-1 encoding. Parameters which contain a space must be enclosed in double quotes (E.g.: popen("aCommand", "\"par 1\" par2", "r"); ). The function shellEscape converts a string, such that it can be used as parameter for popen (E.g.: popen("aCmd", shellEscape("par 1") & " par2", "r"); ). The commands supported and the format of the parameters are not covered by the description of the popen function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen (in string: cmdAndParams, in string: mode)

Open a pipe to a shell command. The command reads, respectively writes with Latin-1 encoding. Spaces in the command must be preceded by a backslash (E.g.: popen("do\\ it"); ). Alternatively the command can be enclosed in double quotes (E.g.: popen("\"do it\""); ). Command parameters containing a space must be enclosed in double quotes (E.g.: popen("do_it \"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the popen function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - The command is not representable as operating system path, or mode is illegal.

const func file: popen (in string: command, in array string: paramList, in string: mode)

Open a pipe to a shell command with a paramList. The command reads, respectively writes with Latin-1 encoding.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

paramList - Array of argument strings passed to the command. It is not necessary to quote the parameters, since this function takes care of that.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const proc: close (in popenFile: aPipe)

Wait for the process associated with aPipe to terminate.

Parameters:

aFile - Pipe to be closed (created by 'popen').

Raises:

FILE_ERROR - A system function returned an error.

const func file: popen8 (in string: command, in string: parameters, in string: mode)

Open an UTF-8 encoded pipe to a shell command with parameters. The command reads, respectively writes with UTF-8 encoding. Parameters which contain a space must be enclosed in double quotes (E.g.: popen8("aCommand", "\"par 1\" par2", "r"); ). The function shellEscape converts a string, such that it can be used as parameter for popen (E.g.: popen8("aCmd", shellEscape("par 1") & " par2", "r"); ). The commands supported and the format of the parameters are not covered by the description of the popen8 function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen8 function.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

parameters - Space separated list of parameters for the command, or "" if there are no parameters.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const func file: popen8 (in string: cmdAndParams, in string: mode)

Open an UTF-8 encoded pipe to a shell command. The command reads, respectively writes with UTF-8 encoding. Spaces in the command must be preceded by a backslash (E.g.: popen8("do\\ it"); ). Alternatively the command can be enclosed in double quotes (E.g.: popen8("\"do it\""); ). Command parameters containing a space must be enclosed in double quotes (E.g.: popen8("do_it \"par 1\" par2"); ). The commands supported and the format of the parameters are not covered by the description of the popen8 function. Due to the usage of the operating system shell and external programs, it is hard to write portable programs, which use the popen8 function.

Parameters:

cmdAndParams - Command to be executed and optional space separated list of parameters. Command and parameters must be space separated.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - The command is not representable as operating system path, or mode is illegal.

const func file: popen8 (in string: command, in array string: paramList, in string: mode)

Open an UTF-8 encoded pipe to a shell command with a paramList. The command reads, respectively writes with UTF-8 encoding.

Parameters:

command - Name of the command to be executed. A path must use the standard path representation.

paramList - Array of argument strings passed to the command. It is not necessary to quote the parameters, since this function takes care of that.

mode - A pipe can be opened with the binary modes "r" (read) and "w" (write) or with the text modes "rt" (read) and "wt" (write).

Returns:

the pipe file opened, or STD_NULL if it could not be opened.

Raises:

RANGE_ERROR - command is not representable as operating system path, or mode is illegal.

const proc: close (in popen8File: aPipe)

Wait for the process associated with aPipe to terminate.

Parameters:

aPipe - UTF-8 encoded pipe to be closed (created by 'popen8').

Raises:

FILE_ERROR - A system function returned an error.