Inq can be invoked as a graphical client, as a server (to which several clients connect) or at the command line, reading an input stream to verify scripts or run stand-alone applications. There is also a client to load scripts into a server.
A generic launcher command, inq, takes the following arguments:
inq [-server|-client|-load] <args...>
- Starts an Inq server. By default, the server will listen on port 6556 for connections from Inq clients made using the native speakinq:// protocol and 6557 for the secure equivalent speakinqs://.
- Starts the Inq GUI client. Server login parameters can be entered at the login window or supplied on the command line.
- Runs the client utility to load scripts into the server. Server login parameters are entered on the command line.
If none of -server, -client or -load are specified then command-line mode is assumed. Any trailing arguments are passed through to the invocation.
This section introduces each Inq mode. We will revisit them when describing how to run the example applications.
Invoking The Server
The server is started as follows:
> inq -server Inq Server Copyright (c) InqWell Ltd 2002-2011 Java Compiler Compiler Version 3.2 Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. DeadlockScanner Started Server Started speakinq Socket Listener Started on port 6556
The server requires the system property inq.home to be set so that it can verify administrator login requests (see section on server administration). The launcher establishes this as the value of the INQHOME environment variable.
The Inq server starts a listener process and awaits connections from clients. The speakinq protocol uses plain sockets and a listener is always started. If the JavaTM system properties of javax.net.ssl.keyStore (and if necessary javax.net.ssl.keyStorePassword) are set the server starts a SSL listener on the default port of 6557. Clients connect to this port using URLs of the form speakinqs://.
When launching the server, the following command line arguments are available
- -speakinqport <port-number>
- overrides the default plain socket port of 6556 to the specified <port-number>
- -speakinqsport <port-number>
- overrides the default SSL socket port of 6557 to the specified <port-number>
Invoking The GUI Client
The Inq GUI client connects to a server instance from which it downloads the scripts that define it. The following invocation brings up the login window:
>inq -client Inq Client Copyright (c) InqWell Ltd 2002-2011 Java Compiler Compiler Version 3.2 Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. JDateChooser Copyright (c) Kai Toedter 1999 - 2006 TableLayout Copyright (c) 2001 Daniel Barbalace. All rights reserved.
When connecting to a server, as well as the URL of the server to connect to, the client supplies a username, password and package. If these are supplied as command line arguments then the login window is not shown.
As we will see later, functions and services written in Inq script are organised into packages. A package is a sub-division of the global name space and can be used to host several different applications in the same Inq server.
As login attempts are made the client maintains a list of the usernames, packages and server URLs used for easy selection. If an incomplete set of command line arguments are specified then these are loaded into the GUI before the login window is shown, leaving the user to enter those that remain. Use the following arguments as required:
-package <package specification>
-server <server url>
Loading Server Scripts
An Inq environment, whether client or server, can do nothing until the scripts that define its operation have been loaded. The GUI client obtains its scripts from the server it is connected to. The server must be loaded using a client utility provided for this purpose. This is similar to loading a database server with tables and stored procedures.
Here is an example invocation of Inq to do this:
inq -load \ -server speakinq://localhost \ -url file:app/examples/petstore/psBoot.inq \ -u admin \ -p inqwell
This command instructs the server at localhost to run the script at the URL file:app/examples/petstore/psBoot.inq, which is resolved by the server.
The Server Administrator Password
To load scripts into the server the client utility must log in as the server administrator. The default administrator password is inqwell. This can be changed using the adminpwd.inq utility as a command line script on the server host itself. This is available in the $INQHOME/bin directory. If invoked without arguments a GUI is shown:
If the environment is headless then the -l flag uses the terminal:
inq -in bin/adminpwd.inq -l Password was last set on Sun Apr 22 18:08:55 BST 2007 Enter password (will echo!):
Entering no password aborts the process.
Running Command Line Scripts
Stand-alone scripts are useful for writing utilities or checking whether a file parses correctly.
Inq reads from standard input, or from the URL specified by the -in argument. If you have downloaded the Inq distribution and assuming you are in the examples/gui directory, try the centigrade-to-fahrenheit example coded in C2F.inq.
The command inq -in C2F.inq will show the window below:
Try moving the sliders and entering values into the text fields.
The -in argument requires a URL. If the URL is relative it is resolved with respect to the current working directory. Absolute file paths on the local host require a URL specifying the file:// protocol. For example, on a Windows system the path C:\inqwell\doc\src\documentation\content\xdocs\primer\examples\array.inq will resolve correctly with the url of file:///C:/inqwell\doc\src\documentation\content\xdocs\primer\examples\array.inq
Every Inq statement has a return value (although this can be null). When running scripts at the command line, the -show argument writes the value of each statement to stdout. At a tty prompt, enter the following text (the results are interspersed and shown in bold):
>inq -show array a = (2.3, 1, 0.5, 6); [2.3, 1, 0.5, 6] sort(a, $loop); [0.5, 1, 2.3, 6] <EOF> Inq done
This small example also illustrates how, in general, Inq manipulates data nodes without regard for what specific type they are. The literal values 2.3 and 0.5 are of type float whereas 1 and 6 are ints, however the array can be sorted regardless of this fact.
The shebang Flag
On Linux/Unix systems and if you create a link of the form /bin/inq -> $INQHOME/bin/inq you can run command line scripts directly.
Inq recognises the -shebang argument for this purpose. Scripts should begin with the line
#! /bin/inq -shebang
and be executable.
Accessing Command Line Arguments
Inq processes the command line arguments according to the following rules:
- Named arguments, specified as -name value, are made available at $catalog.argsMap in all modes, and at argsMap when running from the command line. The minus sign is removed, so the argument -foo bar generates argsMap.foo whose value is the string bar.
- Arguments can be multi-valued. For example, if an application expects the multi-valued argument -foo bar1 bar2 bar3 the array of strings is available at argsMap.arrays.foo. The first value is at argsMap.foo and script may check this path to see if the argument is present at all.
- Boolean arguments, that is arguments whose presence implies the value true are assumed when two argument names appear in succession and for any trailing name. For example -foo -bar widgets yields argsMap.foo as boolean true and argsMap.bar as the string widgets. The same result is given by -bar widgets -foo.
In command line mode, the following additional support is available:
- Tokens from the command line are placed at args as an array. The absolute URL of the the script file is at args.
- The absolute URL of the the script file is available at argsMap.absin.