Beginning of the statements which define a figure.
beginfigure beginfigure(optname1, optvalue1, ...)
beginfigure begins a sequence of statements which define a single figure. The sequence ends with endfigure. Figures which are produced with a single graphical command need not beginfigure/endfigure, except to provide options.
beginfigure(optname1,optvalue1,...) also sets figure options. The following options are supported.
| size | [width, height] |
| filetype | 'gif', 'png', or 'jpeg' |
| quality | number from 0 (worst) to 100 (best) |
| transparency | true if the border is transparent |
| font | 'sans-serif', 'serif', or 'monospace' |
| kind | 'plain', 'interactive', or 'forminput' |
| stamp | string displayed at the bottom right of the figure |
| name | figure name |
| fd | file descriptor the image is written to |
Most options override the default values which can be specified in Apache configuration file. Options 'kind' and 'name' are used for figures which can be clicked by the user.
Figures are normally written as temporary files and the HTML code required to display them as inline images is written to the HTML document sent to the client. This is done automatically; all that has to be done is executing graphical commands bracketed by beginfigure and endfigure (or just the graphical commands for simplest cases). It is also possible to store them manually into files; for instance, as a first step to archive graphical results into a database. Option 'fd' is used for that purpose. Its value should be the file descriptor for binary output obtained with fopen or similar functions. The file should be closed afterwards. Specifying 'fd' disables the output of HTML code for an inline image.
Plain image:
beginfigure('filetype', 'gif');
plot(rand(10));
endfigure;
A temporary gif file containing the plot is stored at the path specified in the Apache configuration file, and Sysquake Remote produces HTML code like the following:
<img src="/path/doc.sqr?__im=283.gif"
width="300" height="200" alt="" />
Interactive image:
beginfigure('filetype', 'gif', 'kind', 'interactive');
plot(rand(10));
endfigure;
The same temporary image file is stored on the server, but Sysquake Remote produces the following HTML code:
<form method="get" action="/path/doc.sqr">
<input type="hidden" name="_scflags" value="0">
<input type="hidden" name="_scx" value="13.8115">
<input type="hidden" name="_scy" value="-454.7028">
<input type="hidden" name="_scox" value="31.44">
<input type="hidden" name="_scoy" value="184.48">
<input type="image" name="_im" border="0"
src="/path/doc.sqr?__im=732.gif"
width="300" height="200" alt="" />
</form>
The hidden fields are what getclick expects to convert image coordinates (with pixel units and top-left origin) to the coordinates implied by the Sysquake Remote graphical commands. When the user clicks into the image, the same SQR file is reloaded and the position of the click can be obtained with getclick. Typically, getclick is called at the beginning of the SQR file; if it gives an empty structure, the initial page is displayed; otherwise, the coordinates of the point clicked by the user is used in an appropiate manner.
Form input image:
beginfigure('filetype', 'gif', 'kind', 'forminput');
plot(rand(10));
endfigure;
Sysquake Remote produces the same HTML code as for interactive images, but without the tags which begin and end the form. This makes it suitable for images which are part of a more complex form, for example when a different page is targetted by the action or when the user can provide other kinds of input.
<input type="hidden" name="_scflags" value="0">
<input type="hidden" name="_scx" value="13.8115">
<input type="hidden" name="_scy" value="-454.7028">
<input type="hidden" name="_scox" value="31.44">
<input type="hidden" name="_scoy" value="184.48">
<input type="image" name="_im" border="0"
src="/path/doc.sqr?__im=978.gif"
width="300" height="200" alt="" />
End of the statements which define a figure.
endfigure
endfigure ends a sequence of statements which define a single figure, which began with beginfigure.
Change string so that it can be passed to the shell as an argument.
stre = escapeshellarg(str)
escapeshellarg(str) changes string str so that it can be used as a single argument in a shell command without being interpreted by the shell. Single quote and backslash characters are escaped with backslash characters, and the result is placed between single quotes.
escapeshellarg should be used when a string coming from an untrusted source is passed as an argument to a shell command.
escapeshellarg('abc\' \\x');
'abc\' \\x'
str = 'x; cat /etc/passwd';
cmd = sprintf('echo %s\n', escapeshellarg(str))
echo 'x; cat /etc/passwd'
Change string so that all characters with a special meaning for the shell are escaped.
stre = escapeshellcmd(str)
escapeshellcmd(str) changes string str so that all characters which have a special meaning to the shell (except for blanks) are escaped with a backslash. The following characters are escaped:
' " ^ ` ; & \ > < * ? [ ] $
escapeshellcmd should be used when a string coming from an untrusted source is passed to a shell command as multiple arguments.
escapeshellcmd('; echo `cat /etc/pwd`');
\; echo \`cat /etc/pwd\`
List of figures.
list = figurelist
figurelist gives the list of all figures generated until now. Each element of the list is a structure with the following fields:
| title | figure title set with title |
| path | absolute path of the file |
This function cannot be called from the sandbox.
Mouse click in an image.
s = getclick
getclick gives a structure whose members give the location of a mouse click on an image created with beginfigure/endfigure. The location is translated from pixel coordinates to the coordinates used to produce the figure. The following fields are defined:
| x | horizontal coordinate |
| y | vertical coordinate |
| z | coordinates as a complex number |
| xp | pixel horizontal coordinate |
| yp | pixel vertical coordinate |
| name | figure name, or '' if none was defined |
If the form elements which permit to get and translate the click location are not found in the request, getclick gives an empty structure, which can be tested with isempty or isfield.
Encode characters with a special meaning in HTML.
stre = htmlspecialchars(str)
htmlspecialchars(str) encodes the special characters in its string argument str such that when the result is interpreted as HTML or XML, it gives back str. The following characters are converted:
| Character | Encoding |
|---|---|
| & | & |
| < | < |
| > | > |
| " | " |
htmlspecialchars should be used when arbitrary data must be displayed as is in HTML code.
cfrag = 'x = 1 << 15';
fprintf('<p>C fragment: <samp>%s</samp></p>',
htmlspecialchars(cfrag));
<p>C fragment: <samp>x = 1 << 15</samp></p>
HTTP variable.
str = http(name)
http(name) gets the value of the HTTP variable specified by string name. Most names correspond to those defined by CGI scripts; their case is not significant.
httpvars, httpheader, getclick
Get or set an HTTP header line.
s = httpheader value = httpheader(name) httpheader(name, value)
Without input argument, httpheader gives a structure whose fields are the values of the HTTP header lines as strings. Field names are the HTTP header names, without trailing colon.
httpheader(name) gets the value of an HTTP header line specified by string name. The header name must not contain a trailing colon. The result is a string.
httpheader(name,value), with two string input arguments, sets or replaces the value of a header line. No output must be produced before HTTP header lines are added or replaced, be it with HTML code or with LME functions.
Typical result of httpheader without input argument:
Accept: '*/*' Accept-Language: 'en-us;q=0.60, en;q=0.40' Connection: 'close' Content-Length: '27' Content-Type: 'text/html' Host: '127.0.0.1' Referer: 'http://127.0.0.1/test-httpheader.sqr' User-Agent: 'Mozilla/5.0'
To add a custom header line, insert a code fragment before anything else in the SQR file:
<?sqr
httpheader('Company', 'Calerga Sarl');
?>
<html>
...
</html>
The same approach should be followed to change a standard header line, such as the content type:
<?sqr
httpheader('Content-type', 'image/png');
imagewrite(1, rand(10), imageset('Type','png'));
?>
Values submitted in a form.
s = httpvars s = httpvars(method)
httpvars gives a structure whose members are the variables sumitted by the client in a GET or POST request. Names correspond to the element names in the HTML form. Values are decoded as with function urldecode.
httpvars(method) uses the contents of the query string if method is 'GET' or the posted data if method is 'POST'.
Since the client can submit anything and is not constrained by the form structure, field existence (or absence) and value should be checked carefully, for instance with function isfield or in a try/catch block.
Begin a new session.
sessionbegin
sessionbegin begins a new session.
End a new session.
sessionend
sessionend terminates the current session.
Fetch the current session variable.
v = sessionfetchvar
sessionfetchvar retrieves the session variable associated with the current session which was saved in the session database on the server with sessionstorevar. If there is no session variable for the current session, sessionfetchvar returns the empty array [].
Session ID string.
str = sessionid
str = sessionid('name')
str = sessionid('id')
str = sessionid('form')
sessionid gives a string which defines an HTTP variable for the session ID. The string has the format 'key=value'. The session ID string can be passed to other pages in the same session, or used as a key in a database to retrieve session-specific data.
With an input argument, sessionid gives the session ID in a different format: sessionid('name') gives the name of the key ('LMESESSIONID'), sessionid('id') gives only the session ID without the key, and sessionid('form') gives a string which defines a name and a value suitable for use in a form input element.
Link to another page in the same session:
<a href="anotherPage?<?sqr= sessionid ?>">link</a>
Different formats:
sessionid
LMESESSIONID=123456789012
sessionid('name')
LMESESSIONID
sessionid('id')
123456789012
sessionid('form')
name="LMESESSIONID" value="123456789012"
List of sessions in the session database.
list = sessionlist
sessionlist gives the list of all session ID stored in the database of session ID.
Discard all sessions in the session database.
sessionresetall
sessionresetall resets the database of sessions on the server, making all session keys invalid.
Fetch the current session variable.
sessionstorevar(v)
sessionstorevar(v) stores v as the session variable associated with the current session in the session database on the server. v can be any kind of data, such as a structure. If it already exists, sessionstorevar replaces it. It can be retrieved with sessionfetchvar.
Decode the encoding of data in a query.
str = urldecode(stre)
urldecode(stre) decodes the special characters in its string, which is typically a part of a GET or POST query. httpvars does it automatically.
urldecode('Hello%2C+World%21')
Hello, World!
Encode a string to a URL-friendly format.
stre = urlencode(str)
urlencode(str) encodes the special characters in its string argument str such that it can be a part of a URL. Letters, digits and characters .-_ (dot, minus and underscore) are preserved; spaces are replaced with + (plus); and all other characters are encoded with a percent sign and two lowercase hexadecimal digits. This encoding corresponds to what Web browsers do to data submitted in forms.
urlencode('Hello, World!')
Hello%2c+World%21
name = 'Joe Jr.';
fprintf('<a href="http://foo.bar/reg.cgi?name=%s">click</a>', ...
urlencode(name));
<a href="http://foo.bar/reg.cgi?name=Joe+Jr.">click</a>