Shell Commands with os_process¶
Attention
The os_process
type has been deprecated and this documentation has
been superseded by the new sys_process
type.
Lasso provides the ability to execute local processes or shell commands through
the os_process
type. This type allows local processes to be launched
with an array of parameters and shell variables. Some processes will execute and
return a result immediately. Other processes can be left open for interactive
read/write operations. The os_process
type enables Lasso users to do
tasks such as execute AppleScripts, print PDF files, and filter data through
external applications.
The os_process
type works across all three platforms that Lasso
supports. The UNIX underpinnings of OS X and Linux mean that those two operating
systems can run many of the same commands and shell scripts. Windows presents a
very different environment including DOS commands and batch files.
The os_process
type is implemented in an LCAPI module that is loaded by
default with Lasso Server, but not loaded when executing Lasso scripts from the
command line. To load the LCAPI module for use with Lasso shell scripts, place
the following line of code in your script:
// If LASSO9_MASTER_HOME is specified, find module there
// Otherwise, find it in the LASSO9_HOME path
lcapi_loadModule((sys_masterHomePath || sys_homePath) + '/LassoModules/OS_Process.' + sys_dll_ext)
For more information on writing shell scripts with Lasso, see the Command-Line Tools chapter.
Using os_process¶
-
type
os_process
¶ Deprecated since version 9.2: Use sys_process instead.
-
os_process
(...) The
os_process
type allows a developer to create a new process on the machine and both read from and write data to it. The process is usually closed after theos_process
object is destroyed, but can optionally be left running. Theos_process
type shares many of the same member methods and conventions as thefile
type.
-
os_process->
open
(command::string, arguments::trait_array=?, env::trait_array=?)¶ Opens a new process. The command string should consist of any path information required to find the executable and the executable’s name. An optional arguments array can be given. Any arguments are converted to strings and passed to the new process. An optional array of environment strings may also be passed in. Both of these optional arrays will be passed to the new process. The command string should be identical to what would have been typed on the command line with the Lasso site folder as the current working directory.
-
os_process->
read
(length::integer=?) → bytes¶ Reads the specified number of bytes from the process. Returns a bytes object. The number of bytes of data actually returned from this method may be less than the specified number, depending on the number of bytes that are actually available to read. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.
-
os_process->
readError
(length::integer=?) → bytes¶ Reads the specified number of bytes from standard error output for the process. Returns a bytes object. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.
-
os_process->
readLine
() → string¶ Reads data up until a carriage return or line feed. Returns a string object created by using the current encoding set for the instance.
-
os_process->
readString
(length::integer=?) → string¶ Reads the specified number of bytes from the process. Returns a string object created by using the current encoding set for the instance. Calling this method without a byte count will read all bytes as they become available until the peer process terminates.
-
os_process->
write
(data::string)¶
-
os_process->
write
(data::bytes) Writes the data to the process. If the data is a string, the current encoding is used to convert the data before being written. If the data is a bytes object, the data is sent unaltered.
-
os_process->
setEncoding
(encoding::string)¶ Sets the encoding for the instance. The encoding controls how string data is written via
os_process->write
and how string data is returned viaos_process->readString
. By default, UTF-8 is used.
-
os_process->
isOpen
() → boolean¶ Returns “true” as long as the process is running. After the process is terminated, it will return “false”.
-
os_process->
detach
()¶ Detaches the
os_process
object from the process. This will prevent the process from terminating when theos_process
object is destroyed.
-
os_process->
close
()¶ Closes the connection to the process. This will cause the process to terminate unless it has previously been detached from the
os_process
object by callingos_process->detach
.
-
os_process->
closeWrite
()¶ Closes the “write” portion of the connection to the process. This results in the process’s standard input file being closed.
OS X and Linux Examples¶
This section includes several examples of using os_process
on OS X. Except for
the AppleScript example, all of these examples should also work on Linux
installations.
Echo¶
This example uses the /bin/echo command to simply echo the input back to STDOUT, which is then read by Lasso:
local(os) = os_process('/bin/echo', (: 'Hello World!'))
#os->read->encodeHtml
#os->close
// => Hello World!
List¶
This example uses the /bin/ls command to list the contents of a directory:
local(os) = os_process('/bin/ls', (: '/' + sys_homePath))
#os->readString->encodeHtml(true, false)
#os->close
// =>
// LassoApps
// LassoModules
// LassoStartup
// SQLiteDBs
// lasso.err.txt
// lasso.fastcgi.sock
// lasso.out.txt
Create File¶
This example uses the /usr/bin/tee command to create a file “test.txt” in the site folder. The code does not generate any output, it just creates the file.
local(os) = os_process
handle => {
#os->close
}
#os->open('/usr/bin/tee', (: './test.txt'))
#os->write('This is a test\n')
#os->write('This is a test\n')
#os->close
Print¶
This example uses the /usr/bin/lpr command to print some text on the default printer. The result in this case is a page that contains the phrase “This is a test” at the top. This style of printing can be used to output text data using the default font for the printer. The lpr command can also be used with some common file formats such as PDF files.
local(os) = os_process('/usr/bin/lpr')
#os->write('This is a test')
#os->write(bytes->import8Bits(4)&)
#os->closeWrite
#os->close
AppleScript¶
This example uses the /usr/bin/osascript command to run a simple AppleScript. AppleScript is a full scripting language that provides access to the system and running applications in OS X. The script shown returns the current date and time:
local(os) = os_process('/usr/bin/osascript', (: '-'))
#os->write('return current date')
#os->closeWrite
#os->read->encodeHtml
#os->close
// => Tuesday, March 21, 2006 11:52:34 AM
Web Request¶
This example uses the /usr/bin/curl command to fetch a web page and
return the results. The curl
type or include_url
method can be used
for the same purpose. Only the first part of the output is shown.
local(os) = os_process('/usr/bin/curl', (: 'http://www.apple.com/'))
#os->read->encodeHtml
#os->close
// =>
// <!DOCTYPE html>
// <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
// <head>
// <meta charset="utf-8" />
// <meta name="Author" content="Apple Inc." />
// ... rest of response ...
Windows Examples¶
This section includes several examples of using os_process
on Windows. Each of
the examples uses the command-line processor CMD with the option “/C”
to interpret an individual command.
Echo¶
This example uses the CMD processor with an ECHO command to simply echo the input back to Lasso:
local(os) = os_process('cmd', (: '/C ECHO Hello World!'))
#os->readString->encodeHtml
#os->close
// => Hello World!
List¶
This example uses the CMD processor with a DIR command to list the contents of a directory. The “/B” option instructs Windows to only list the contents of the directory without extraneous header and footer information.
local(os) = os_process('cmd', (: '/C DIR /B .'))
#os->readString->encodeHtml
#os->close
// =>
// JavaLibraries
// JDBCDrivers
// LassoApps
// LassoModules
// LassoStartup
// SQLiteDBs
// JDBCLog.txt
// lasso.err.txt
// lasso.out.txt
Help¶
This example uses the CMD processor with a HELP command to show the help information for a command. The start of the help file for CMD itself is shown. Running HELP without a parameter will return a list of all the built-in commands supported by the command processor.
local(os) = os_process('cmd', (: '/C HELP cmd'))
#os->readString->encodeHtml
#os->close
// =>
// Starts a new instance of the Windows XP command interpreter
// CMD [/A | /U] [/Q] [/D] [/E:ON | /E:OFF] [/F:ON | /F:OFF] [/V:ON | /V:OFF] [[/S] [/C | /K] string]
// /C Carries out the command specified by string and then terminates
// /K Carries out the command specified by string but remains
// /Q Turns echo off
// /A Causes the output of internal commands to a pipe or file to be ANSI
// /U Causes the output of internal commands to a pipe or file to be Unicode
Multiple Commands¶
This example uses the CMD processor interactively to run several commands. The processor is started with a parameter of “/Q” which suppresses the echoing of commands back to the output. The result is exactly the same as what would be provided if these commands were entered directly into the command line shell. In order to process the results, it would be necessary to strip off the header and the directory prefix from each line.
local(os) = os_process('cmd', (: '/Q'))
#os->write('ECHO Line One\r\n')
#os->write('ECHO Line Two\r\n')
#os->read->encodeHtml
#os->close
// =>
// Microsoft Windows XP [Version 5.1.2600]
// (C) Copyright 1985-2001 Microsoft Corp.
// C:\Program Files\LassoSoft\Lasso Instance Manager\home>Line One
// C:\Program Files\LassoSoft\Lasso Instance Manager\home>Line Two
Batch File¶
This example uses the CMD processor to process a batch file. The contents of batch file “batch.bat” is shown below. The file is assumed to be located in the folder for the current site in the Lasso Server application folder.
@ECHO OFF
CLS
ECHO This file demonstrates how to use a batch file.
The batch file is executed by calling its name as a command. The results of the batch file are then output. Using a batch file makes executing a sequence of commands easy since all the code can be perfected using local testing before it is run through Lasso.
local(os) = os_process('cmd', (: '/C batch.bat'))
#os->readString->encodeHtml
#os->close
// => This file demonstrates how to use a batch file.