Chapter 4.4:  Shell Access

[TOP] [UP] [PREV] [NEXT]

CML provides one comprehensive function ($xshell()) for accessing the Unix (or NT) command interpreter or "shell" (and thereby running commands or scripts from the shell). 

For historical reasons (and to provide backward compatibility with earlier versions CML), several other shell functions are provided that implement subcases of $xshell().

$xshell(output synch effective command)        {protected}

Runs command in a shell.  Output controls what happens to the output from the command.  If it is 0, the output is ignored.  If greater than 0, the function evaluates to the output from the command.  Values of 1, 2, and 3 cause default translation, translation from EUC, and translation from SJIS, respectively.

Synch controls synchronous operation.  If 1, the command executes synchronously, i.e. $xshell() does not "return" until the command is complete.  If 0, the command executes asynchronously, and $xshell() returns immediately (with no output, regardless of the value of output).

Finally, on Unix systems, effective controls the permissions with which command is run.  If 1, the command runs with its real id as the Caucus id (see the parameter Caucus_ID in the swebd.conf configuration file).  If 0, the command runs as the "real" id, as specified by the parameter Real_ID in swebd.conf. 

Warnings and Notes: 

• Unix: unless it is specifically necessary to execute shell commands that can access the Caucus data files, it is strongly recommended that all shell functions run as a "real" id that has limited access to Caucus and the rest of the system.  This can best be accomplished by (a) using a value of 0 for effective, and (b) by making sure that Caucus is started from "root", with a swebd.conf Real_ID parameter of "nobody", or some similarly unprivileged id.

• NT: eff_real has no effect; all xshell() commands run as the "caucus" userid and can thus affect the Caucus data files.  Be careful!

• NT: if command references a .EXE or .BAT file, you must include the extension as part of the file name.

• NT: using stdin ("standard input") inside a batch file may cause the batch file (and thus the Caucus process, which is waiting for it) to "hang".  For example, batch commands like "echo Y|deltree xyz" seem susceptible to this problem.

Note also that all of the shell functions are ignored (have no effect) when inside a $protect() function.

$sleep(secs)        {protected}

Sleeps for secs seconds.  Often a good idea after running a shell script or sweba program to allow it time to complete.

---

The remaining functions are all subcases of $xshell(), and are provided for historical compatibility.

$shell(command)        {protected}

Runs command in a shell.  The function evaluates to the output from command.  Example:

"It is now: $shell(date)

Equivalent to $xshell (1 1 0 command).

$jshell(type command)        {protected}

Runs command in a shell.  The function evaluates to the output from command, expecting that the command produces japanese text in EUC coding (type=2) or SJIS coding (type=3).  (For more information about language type codes, see the DISKFORMAT parameter in swebd.conf.)

Equivalent to $xshell (type 1 0 command).

$silent(command)        {protected}

Runs command in a shell.  The output is ignored.  The function evaluates to nothing, i.e. it effectively disappears.  The example logs a user's userid to a temporary file.

" $silent(echo $userid() >>/tmp/log)

Equivalent to $xshell (0 1 0 command).

$asynch(command)        {protected}

Runs command in a shell, immediately, without waiting for command to finish.  Equivalent to $xshell (0 0 0 command).