File: erl_call.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (387 lines) | stat: -rw-r--r-- 9,553 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>erl_call</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>erl_call</H1>
</CENTER>

<H3>COMMAND</H3>
<DIV CLASS=REFBODY>
erl_call
</DIV>

<H3>COMMAND SUMMARY</H3>
<DIV CLASS=REFBODY>
Call/Start a Distributed Erlang Node
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P><CODE>erl_call</CODE> makes it possible to start and/or communicate with 
a distributed Erlang node. It is built upon the <CODE>erl_interface</CODE> 
library as an example application. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all 
communication with the Erlang <STRONG>rex server</STRONG>, using the standard Erlang RPC facility. It does not require any special
software to be run at the Erlang target node.

<P>The main use is to either start a distributed Erlang node
or to make an ordinary function call. However, it is also
possible to pipe an Erlang module to <CODE>erl_call</CODE> and have it
compiled, or to pipe a sequence of Erlang expressions to be evaluated
(similar to the Erlang shell).

<P>Options, which cause <CODE>stdin</CODE> to be read, can be used with
advantage 
as scripts from within (Unix) shell scripts. Another 
nice use of <CODE>erl_call</CODE> could be from (http) CGI-bin scripts.

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="erl_call"><STRONG><CODE>erl_call &#60;options&#62;</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Each option flag is described below with its name, type and
         meaning. 
        
<P>
<DL>

<DT>
-a [Mod [Fun [Args]]]]
</DT>

<DD>
(<STRONG>optional</STRONG>): Applies the specified function
         and returns the result. <CODE>Mod</CODE> must be specified, however
         <STRONG>[]</STRONG> is assumed for unspecified <CODE>Fun</CODE> and <CODE>Args</CODE>. <CODE>Args</CODE> should
         be in the same format as for <CODE>erlang:apply/3</CODE>. Note
         that this flag takes exactly one argument, so quoting
         may be necessary in order to group <CODE>Mod</CODE>, <CODE>Fun</CODE>
         and <CODE>Args</CODE>, in a manner dependent on the behavior
         of your command shell.
         <BR>

         <BR>

         
</DD>

<DT>
-c Cookie
</DT>

<DD>
(<STRONG>optional</STRONG>): Use this option to specify a certain cookie. If no cookie is specified, the <CODE>~/.erlang.cookie</CODE> file is read and its content are used as cookie. The Erlang node we want to communicate with must have the same cookie.
         <BR>

                 
</DD>

<DT>
-d
</DT>

<DD>
(<STRONG>optional</STRONG>): Debug mode. This causes all IO to be output
         to the file <CODE>~/.erl_call.out.Nodename</CODE>, where <CODE>Nodename</CODE>
         is the node name of the Erlang node in question.
         <BR>

         <BR>

         
</DD>

<DT>
-e
</DT>

<DD>
(<STRONG>optional</STRONG>): Reads a sequence of Erlang expressions, separated
         by '<STRONG>,</STRONG>' and ended with a '<STRONG>.</STRONG>', from <CODE>stdin</CODE> until
         EOF (Control-D). Evaluates the expressions and returns the result from 
         the last expression. Returns <CODE>{ok,Result}</CODE> if successful.
         <BR>

         <BR>

         
</DD>

<DT>
-h HiddenName
</DT>

<DD>
(<STRONG>optional</STRONG>): Specifies the name of the hidden node
         that <CODE>erl_call</CODE> represents.
         <BR>

         <BR>

         
</DD>

<DT>
-m
</DT>

<DD>
(<STRONG>optional</STRONG>): Reads an Erlang module from <CODE>stdin</CODE> and
         compiles it.
         <BR>

         <BR>

         
</DD>

<DT>
-n Node
</DT>

<DD>
(one of <CODE>-n, -name, -sname</CODE> is required): 
         Has the same meaning as <CODE>-name</CODE> and can still be used for 
         backwards compatibility reasons.
         <BR>

         <BR>

         
</DD>

<DT>
-name Node
</DT>

<DD>
(one of <CODE>-n, -name, -sname</CODE> is required): <CODE>Node</CODE> is the name of the node to be
         started or communicated with. It is assumed that 
         <CODE>Node</CODE> is started with <CODE>erl -name</CODE>, which means that fully 
         qualified long node names are used. 
         If the <CODE>-s</CODE> option is given, an Erlang node will (if necessary) 
         be started with <CODE>erl -name</CODE>.         
         <BR>

         <BR>

         
</DD>

<DT>
-q
</DT>

<DD>
(<STRONG>optional</STRONG>): Halts the Erlang node specified
         with the -n switch. This switch overrides the -s switch.
         <BR>

         <BR>

         
</DD>

<DT>
-r
</DT>

<DD>
(<STRONG>optional</STRONG>): Generates a random name of the hidden node
         that <CODE>erl_call</CODE> represents.
         <BR>

         <BR>

         
</DD>

<DT>
-s
</DT>

<DD>
(<STRONG>optional</STRONG>): Starts a distributed Erlang node if necessary.
         This means that in a sequence of calls, where the '<CODE>-s</CODE>'
         and '<CODE>-n Node</CODE>' are constant, only the first call will start
         the Erlang node. This makes the rest of the communication 
         very fast. This flag is currently only available on the Unix platform.
         <BR>

         <BR>

         
</DD>

<DT>
-sname Node
</DT>

<DD>
(one of <CODE>-n, -name, -sname</CODE> is required): <CODE>Node</CODE> is the name of the node to
be started or communicated with. It is assumed that <CODE>Node</CODE> is started with <CODE>erl -sname</CODE> which means that short node names are used.        
If <CODE>-s</CODE> option is given, an Erlang node will be started (if necessary) with <CODE>erl -sname</CODE>.  
         <BR>

         <BR>

         
</DD>

<DT>
-v
</DT>

<DD>
(<STRONG>optional</STRONG>): Prints a lot of <CODE>verbose</CODE> information.
         This is only useful for the developer and maintainer of <CODE>erl_call</CODE>.
         <BR>

         <BR>

         
</DD>

<DT>
-x ErlScript
</DT>

<DD>
(<STRONG>optional</STRONG>): Specifies another name of the Erlang start-up script
         to be used. If not specified, the standard <CODE>erl</CODE> start-up script
         is used.
         <BR>

         
</DD>

</DL>

</DIV>

<H3>Examples</H3>
<DIV CLASS=REFBODY>

<P>Starts an Erlang node and calls <CODE>erlang:time/0</CODE>.

<PRE>
erl_call -s -a 'erlang time' -n madonna
{18,27,34}
    
</PRE>

<P>Terminates an Erlang node by calling <CODE>erlang:halt/0</CODE>.

<PRE>
erl_call -s -a 'erlang halt' -n madonna
    
</PRE>

<P>An apply with several arguments.

<PRE>
erl_call -s -a 'lists map [{math,sqrt},[1,4,9,16,25]]' -n madonna
    
</PRE>

<P>Evaluates a couple of expressions. The input ends with EOF (Control-D).

<PRE>
erl_call -s -e -n madonna
statistics(runtime),
X=1,
Y=2,
{_,T}=statistics(runtime),
{X+Y,T}.
^D
{ok,{3,0}}
    
</PRE>

<P>Compiles a module and runs it. Again, the input ends with EOF (Control-D). (In the example shown, the output has been formatted afterwards).

<PRE>
erl_call -s -m -a lolita -n madonna
-module(lolita).
-compile(export_all).
start() -&#62;
        P = processes(),
        F = fun(X) -&#62; {X,process_info(X,registered_name)} end,
        lists:map(F,[],P).
^D
[{&#60;madonna@chivas.du.etx.ericsson.se,0,0&#62;,
                  {registered_name,init}},
 {&#60;madonna@chivas.du.etx.ericsson.se,2,0&#62;,
                  {registered_name,erl_prim_loader}},
 {&#60;madonna@chivas.du.etx.ericsson.se,4,0&#62;,
                  {registered_name,error_logger}},
 {&#60;madonna@chivas.du.etx.ericsson.se,5,0&#62;,
                  {registered_name,application_controller}},
 {&#60;madonna@chivas.du.etx.ericsson.se,6,0&#62;,
                  {registered_name,kernel}},
 {&#60;madonna@chivas.du.etx.ericsson.se,7,0&#62;,
                  []},
 {&#60;madonna@chivas.du.etx.ericsson.se,8,0&#62;,
                  {registered_name,kernel_sup}},
 {&#60;madonna@chivas.du.etx.ericsson.se,9,0&#62;,
                  {registered_name,net_sup}},
 {&#60;madonna@chivas.du.etx.ericsson.se,10,0&#62;,
                  {registered_name,net_kernel}},
 {&#60;madonna@chivas.du.etx.ericsson.se,11,0&#62;,
                  []},
 {&#60;madonna@chivas.du.etx.ericsson.se,12,0&#62;,
                  {registered_name,global_name_server}},
 {&#60;madonna@chivas.du.etx.ericsson.se,13,0&#62;,
                  {registered_name,auth}},
 {&#60;madonna@chivas.du.etx.ericsson.se,14,0&#62;,
                  {registered_name,rex}},
 {&#60;madonna@chivas.du.etx.ericsson.se,15,0&#62;,
                  []},
 {&#60;madonna@chivas.du.etx.ericsson.se,16,0&#62;,
                  {registered_name,file_server}},
 {&#60;madonna@chivas.du.etx.ericsson.se,17,0&#62;,
                  {registered_name,code_server}},
 {&#60;madonna@chivas.du.etx.ericsson.se,20,0&#62;,
                  {registered_name,user}},
 {&#60;madonna@chivas.du.etx.ericsson.se,38,0&#62;,
                  []}]
    
</PRE>

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
T.Trnkvist - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>erl_interface 3.5.5.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>