ARS-Simple
view release on metacpan or search on metacpan
html/Simple.html view on Meta::CPAN
<span class="string">form</span> <span class="operator">=></span> <span class="variable">$form</span><span class="operator">,</span>
<span class="string">query</span> <span class="operator">=></span> <span class="variable">$query</span><span class="operator">,</span>
<span class="string">lfid</span> <span class="operator">=></span> <span class="operator">{</span> <span class="variable">label1</span><span class="operator">,</span> <span class="variable">fid1</span><span class="operator">,</span> <span class="...
<span class="operator">}</span><span class="operator">);</span>
</code></pre>
<h1 id="METHODS">METHODS</h1>
<h2 id="new">new</h2>
<p>Constructor for ARS::Simple. There are three required arguments:</p>
<dl>
<dt id="server">server</dt>
<dd>
<p>The name (or possibly IP Address) of the Remedy ARSystem server you wish to connect to.</p>
</dd>
<dt id="user">user</dt>
<dd>
<p>The user you wish to connect as (this is often a user with administrator privilages). Note that while this is a required argument, it may be supplied via the configuration file to avoid lots of scripts with the user (and password) in them (less to...
</dd>
<dt id="password">password</dt>
<dd>
<p>The password to the user you wish to connect as. This may come from the configuration file if set.</p>
</dd>
</dl>
<p>There are a number of optional arguments, they are:</p>
<dl>
<dt id="max_returns">max_returns</dt>
<dd>
<p>Set a limit on how many items may be returned from certain calls. Setting this value to 0 sets unlimited returns. This parameter can also be set on individual calls. <b>Note:</b> This is a system wide configuration change and requires administrato...
<p><b>Note: You should not use a value less than the default system value for this field or you may impact normal operation of your system</b></p>
<p>Example usage:</p>
<pre><code> reset_limit => 0, # unlimited returns</code></pre>
</dd>
<dt id="reset_limit">reset_limit</dt>
<dd>
<p>Once max_returns is used, reset_limit, if set will return the server to nominated max_returns limit (eg 3000), thereby limiting the possible impact on the system of having max_returns set to a high value (eg 0).</p>
<p>Example usage:</p>
<pre><code> reset_limit => 3000, # max returns back to a suitable maximum of 3000</code></pre>
</dd>
<dt id="ars_debug">ars_debug</dt>
<dd>
<p>Turn on, if true (1), the ARSperl debugging output. Not something you would normally use.</p>
</dd>
<dt id="log">log</dt>
<dd>
<p>Pass a object to use to log erros/information to a log file. The log object is expected to have methods <i>exp</i> and <i>msg</i> as per the File::Log object.</p>
</dd>
</dl>
<p>Sample invocation with ALL parameters:</p>
<pre><code> <span class="keyword">use</span> <span class="variable">ARS::Simple</span><span class="operator">;</span>
<span class="keyword">use</span> <span class="variable">File::Log</span><span class="operator">;</span>
<span class="keyword">my</span> <span class="variable">$log</span> <span class="operator">=</span> <span class="variable">File::Log</span><span class="operator">-></span><span class="variable">new</span><span class="operator">();</span>
<span class="keyword">my</span> <span class="variable">$ars</span> <span class="operator">=</span> <span class="variable">ARS::Simple</span><span class="operator">-></span><span class="variable">new</span><span class="operator">(</span><span clas...
<span class="string">server</span> <span class="operator">=></span> <span class="string">'my_server'</span><span class="operator">,</span>
<span class="string">user</span> <span class="operator">=></span> <span class="string">'some_admin'</span><span class="operator">,</span>
<span class="string">password</span> <span class="operator">=></span> <span class="string">'password_for_some_admin'</span><span class="operator">,</span>
<span class="string">log</span> <span class="operator">=></span> <span class="variable">$log</span><span class="operator">,</span>
<span class="string">max_returns</span> <span class="operator">=></span> <span class="number">0</span><span class="operator">,</span> <span class="comment"># allow unlimited returns</span>
<span class="string">reset_limit</span> <span class="operator">=></span> <span class="number">3000</span><span class="operator">,</span> <span class="comment"># reset to a suitable limit after each call using max_returns</span>
<span class="string">ars_debug</span> <span class="operator">=></span> <span class="number">1</span><span class="operator">,</span> <span class="comment"># get a whole lot of debugging information (you real should not need)</span>
<span class="operator">}</span><span class="operator">);</span>
</code></pre>
<h2 id="get_list">get_list</h2>
<p>Method to return an array reference of Entry-Id values for a form. Arguments are passed as an hash reference, with two required parameters, eg:</p>
<pre><code> <span class="comment"># Get theEntry-Id's for all records in the 'User' form.</span>
<span class="keyword">my</span> <span class="variable">$eids</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-></span><span class="variable">get_list</span><span class="operator">(</span><span class...
</code></pre>
<p>The query parameter can be the same format as you would use in the 'User Tool' to query a form, however we recommend the use of field ID's (FID) rather than the default field name as they may change. I prefer to define a hash of the fo...
<pre><code> <span class="keyword">my</span> <span class="variable">%user</span> <span class="operator">=</span> <span class="operator">(</span> <span class="string">UserID</span> <span class="operator">=></span> <span class="number">101</span><spa...
</code></pre>
<p>the a query could be something like</p>
<pre><code> <span class="keyword">my</span> <span class="variable">$query</span> <span class="operator">=</span> <span class="string">qq{ '</span><span class="variable">$user</span><span class="string">{UserID}' LIKE "g%" }</span><span class="operato...
<span class="keyword">my</span> <span class="variable">$eids</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-></span><span class="variable">get_list</span><span class="operator">(</span><span class...
</code></pre>
<h2 id="get_SQL">get_SQL</h2>
<p>Run direct SQL on your server, there is only one required argument, the sql, you may optionally set the max_returns value.</p>
<p>The names of the fields can be found from the Admin Tool, under the database tab for a form. This will be the name of the field used in the database view of the Remedy form. <b>Note</b> you do need to replace spaces with and underscore '_'...
<p>Example method call:</p>
<pre><code> <span class="keyword">my</span> <span class="variable">$data</span> <span class="operator">=</span> <span class="variable">$ars</span><span class="operator">-></span><span class="variable">get_SQL</span><span class="operator">(</span><...
<span class="string">sql</span> <span class="operator">=></span> <span class="string">q{select Login_name, Full_Name from User_X where Login_name like 'g%' order by Login_name}</span><span class="operator">,</span>
<span class="string">max_returns</span> <span class="operator">=></span> <span class="number">0</span><span class="operator">,</span>
<span class="operator">}</span><span class="operator">);</span>
</code></pre>
<p>The return is a hash reference with two keys, numMatches and rows, example:</p>
<pre><code> <span class="variable">$data</span> <span class="operator">=</span> <span class="operator">{</span>
<span class="variable">numMatches</span> <span class="operator">=</span> <span class="operator">></span> <span class="number">2</span><span class="operator">,</span>
<span class="string">rows</span> <span class="operator">=></span> <span class="operator">[</span>
<span class="string">'greg'</span><span class="operator">,</span> <span class="string">'Greg George'</span><span class="operator">,</span>
<span class="string">'geoff'</span><span class="operator">,</span> <span class="string">'Geoffery Wallace'</span><span class="operator">,</span>
<span class="operator">]</span>
<span class="operator">}</span><span class="operator">;</span>
</code></pre>
<h2 id="get_data_by_label">get_data_by_label</h2>
<p>Query a form and get the data back as a hash reference where the keys are the Entry-Id's for the records matched by the query and the value is a hash reference to the fields you requested where the keys are the field names you used and the val...
<pre><code> <span class="keyword">my</span> <span class="variable">$form</span> <span class="operator">=</span> <span class="string">'form'</span><span class="operator">;</span>
<span class="keyword">my</span> <span class="variable">$query</span> <span class="operator">=</span> <span class="string">qq('FID' = "value")</span><span class="operator">;</span>
<span class="keyword">my</span> <span class="variable">$data</span> <span class="operator">=</span> <span class="variable">$ar</span><span class="operator">-></span><span class="variable">get_data_by_label</span><span class="operator">(</span><sp...
<span class="string">form</span> <span class="operator">=></span> <span class="variable">$form</span><span class="operator">,</span>
<span class="string">query</span> <span class="operator">=></span> <span class="variable">$query</span><span class="operator">,</span>
<span class="string">lfid</span> <span class="operator">=></span> <span class="operator">{</span> <span class="variable">label1</span><span class="operator">,</span> <span class="variable">fid1</span><span class="operator">,</span> <span cla...
<span class="operator">}</span><span class="operator">);</span>
<span class="variable">$data</span> <span class="operator">=</span> <span class="operator">{</span>
( run in 0.425 second using v1.01-cache-2.11-cpan-0bd6704ced7 )