add more help pages related to CAPI - check parameters - optional parameters
[scilab.git] / scilab / modules / core / help / en_US / capi / get_optionals.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="get_optionals" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:mml="http://www.w3.org/1998/Math/MathML"
7           xmlns:html="http://www.w3.org/1999/xhtml"
8           xmlns:db="http://docbook.org/ns/docbook">
9   <refnamediv>
10     <refname>get_optionals</refname>
11
12     <refpurpose>C interface function which initialize the list of optional
13     parameters</refpurpose>
14   </refnamediv>
15
16   <refsynopsisdiv>
17     <title>Calling Sequence</title>
18
19     <synopsis>res get_optionals(fname, opts)</synopsis>
20   </refsynopsisdiv>
21
22   <refsection>
23     <title>Parameters</title>
24
25     <variablelist>
26       <varlistentry>
27         <term>fname</term>
28
29         <listitem>
30           <para>the name passed to the C interface. The name of the calling
31           function (of type char *) (input parameter)</para>
32         </listitem>
33       </varlistentry>
34
35       <varlistentry>
36         <term>opts</term>
37
38         <listitem>
39           <para>a C list of optional parameters</para>
40
41           <programlisting> 
42 typedef struct rhs_opts__ {
43   int position ; // stack position : -1 if not present
44   char *name; // the name of the variable
45   char *type; // a Scilab type (like "d") representing the type of the variable
46   int m,n; // the size of the variable
47   unsigned long int l; // a pointer to the Scilab stack
48 } rhs_opts;
49  </programlisting>
50         </listitem>
51       </varlistentry>
52
53       <varlistentry>
54         <term>res</term>
55
56         <listitem>
57           <para>if no optional parameters has been sent, the res = 0.
58           Otherwise, res = 1.</para>
59         </listitem>
60       </varlistentry>
61     </variablelist>
62   </refsection>
63
64   <refsection>
65     <title>Description</title>
66
67     <para>C interface function which initialize the list of optional
68     parameters. You must include stack-c.h to benefit from this
69     function.</para>
70   </refsection>
71
72   <refsection>
73     <title>Examples</title>
74
75     <para>A more complete example is available in the directory
76     example/optional_parameters.</para>
77
78     <programlisting role="example"> 
79 #include &lt;stack-c.h&gt;
80
81 int sci_optional_parameters(char * fname)
82
83   int m1,n1,l1;
84
85   // optional names must be stored in alphabetical order in opts
86   static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
87                            {-1,"v2","d",0,0,0},
88                            {-1,NULL,NULL,0,0}};
89
90   int minrhs = 1, maxrhs = 1;
91   int minlhs = 1, maxlhs = 3;
92   int nopt, iopos, res;
93   char buffer_name[csiz]; // csiz used for character coding
94
95   nopt = NumOpt();
96
97   CheckRhs(minrhs,maxrhs+nopt);
98   CheckLhs(minlhs,maxlhs);
99
100   // first non optional argument
101   GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
102   
103   if (get_optionals(fname,opts)==0) return 0;
104
105   sciprint("number of optional parameters = %d\n", NumOpt());
106   sciprint("first optional parameters = %d\n", FirstOpt());
107   sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
108   sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
109
110   if (IsOpt(1,buffer_name))
111     sciprint("parameter 1 is optional: %s\n", buffer_name);
112   if (IsOpt(2,buffer_name))
113     sciprint("parameter 2 is optional: %s\n", buffer_name);
114   if (IsOpt(3,buffer_name))
115     sciprint("parameter 3 is optional: %s\n", buffer_name);
116
117   return 0;
118 }
119  </programlisting>
120   </refsection>
121
122   <refsection>
123     <title>See Also</title>
124
125     <simplelist type="inline">
126       <member><link linkend="CheckDims">CheckDims</link></member>
127
128       <member><link linkend="CheckRow">CheckRow</link></member>
129
130       <member><link linkend="CheckScalar">CheckScalar</link></member>
131
132       <member><link linkend="CheckVector">CheckVector</link></member>
133
134       <member><link linkend="OverLoad">CheckOverLoad</link></member>
135
136       <member><link linkend="CheckDimProp">CheckDimProp</link></member>
137
138       <member><link linkend="CheckLength">CheckLength</link></member>
139
140       <member><link linkend="CheckSameDims">CheckSameDims</link></member>
141
142       <member><link linkend="CheckSquare">CheckSquare</link></member>
143
144       <member><link
145       linkend="How to check parameters">HowToCheckParameters</link></member>
146     </simplelist>
147   </refsection>
148 </refentry>