You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jmeter-dev@jakarta.apache.org by se...@apache.org on 2003/10/08 20:49:41 UTC

cvs commit: jakarta-jmeter/xdocs/usermanual functions.xml component_reference.xml

sebb        2003/10/08 11:49:41

  Modified:    xdocs/usermanual functions.xml component_reference.xml
  Log:
  Moved function descriptions into functions page
  
  Revision  Changes    Path
  1.6       +226 -1    jakarta-jmeter/xdocs/usermanual/functions.xml
  
  Index: functions.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-jmeter/xdocs/usermanual/functions.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- functions.xml	13 Jun 2003 14:51:51 -0000	1.5
  +++ functions.xml	8 Oct 2003 18:49:41 -0000	1.6
  @@ -69,6 +69,231 @@
   for you to copy-paste into your test plan wherever you like.</p>
   </subsection>
   
  +<subsection name="14.5 Functions" anchor="functions">
  +
  +<component index="14.5.1" name="__regexFunction">
  +<description><p>The Regex Function is used to parse the previous response using any regular
  +expression (provided by user).  The function returns the template string with variable values filled
  +in.</p>
  +<p>The __regexFunction stores values for future use.  In the sixth parameter, you can specify
  +a reference name.  After this function executes, the same values can be retrieved at later times
  +using the syntax for user-defined values.  For instance, if you enter "refName" as the sixth
  +parameter you will be able to use:
  +<ul>
  +<li>${refName} to refer to the computed result of the second parameter ("Template for the
  +replacement string") parsed by this function</li>
  +<li>${refName_g0} to refer to the entire match  parsed by this function.</li>
  +<li>${refName_g1} to refer to the first group parsed by this function.</li>
  +<li>${refName_g#} to refer to the n<sup>th</sup> group parsed by this function.</li>
  +</ul>
  +</p></description>
  +
  +<properties>
  +        <property name="First arguement" required="Yes">The first argument is the regular expression
  +        to be applied to the response data.  It will grab all matches.  Any parts of this expression
  +        that you wish to use in your template string, be sure to surround in parentheses.  Example:
  +        &amp;lt;a href="(.*)"&amp;gt;.  This will grab the value of the link and store it as the first group (there is
  +        only 1 group).  Another example: &amp;lt;input type="hidden" name="(.*)" value="(.*)"&amp;gt;.  This will
  +        grab the name as the first group, and the value as the second group.  These values can be used
  +        in your template string</property>
  +        <property name="Second argument" required="Yes">This is the template string that will replace
  +        the function at run-time.  To refer to a group captured in the regular expression, use the syntax:
  +        $[group_number]$.  Ie: $1$, or $2$.  Your template can be any string.</property>
  +        <property name="Third argument" required="Yes">The third argument tells JMeter which match
  +        to use.  Your regular expression might find numerous matches.  You have four choices:
  +                <ul><li>An integer - Tells JMeter to use that match.  '1' for the first found match, '2' for the
  +                second, and so on</li>
  +                <li>RAND - Tells JMeter to choose a match at random.</li>
  +                <li>ALL - Tells JMeter to use all matches, and create a template string for each one and then
  +                append them all together.  This option is little used.</li>
  +                <li>A float number between 0 and 1 - tells JMeter to find the Xth match using the formula:
  +                (number_of_matches_found * float_number) rounded to nearest integer.</li>
  +                </ul></property>
  +        <property name="Fourth argument" required="No">If 'ALL' was selected for the above argument
  +        value, then this argument will be inserted between each appended copy of the template value.</property>
  +        <property name="Fifth argument" required="No">Default value returned if no match is found</property>
  +    <property name="Sixth argument" required="No">A reference name for reusing the values parsed by this function.<br></br>
  +        Stored values are ${refName} (the replacement template string) and ${refName_g#} where "#" is the
  +        group number from the regular expression ("0" can be used to refer to the entire match).</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.2" name="__counter">
  +<description><p>The counter generates a new number each time it is called, starting with 1
  +and incrementing by +1 each time.  The counter can be configured to keep each simulated user's values
  +separate, or to use the same counter for all user.  If each user's values is incremented separately,
  +that is like counting the number of iterations through the test plan.  A global counter is like
  +counting how many times that request was run.</p></description>
  +
  +<properties>
  +        <property name="First argument" required="Yes">TRUE if you wish each simulated user's counter
  +        to be kept independent and separate from the other users.  FALSE for a global counter.</property>
  +
  +<property name="Second argument" required="No">A reference name for reusing the value created by this function.<br></br>
  +                Stored values are of the form ${refName}.  This allows you to keep one counter and refer to its value in
  +                multiple places.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.3" name="__threadNum">
  +<description><p>The thread number function simply returns the number of the thread currently
  +being executed.  These numbers are independent of ThreadGroup, meaning thread #1 in one threadgroup
  +is indistinguishable from thread #1 in another threadgroup, from the point of view of this function.</p>
  +
  +<p>There are no arguments for this function.</p>
  +</description>
  +</component>
  +
  +<component index="14.5.4" name="__intSum">
  +<description><p>The intsum function can be used to compute the sum of two or more integer values.
  +</p></description>
  +
  +<properties>
  +        <property name="First argument" required="Yes">The first int value.</property>
  +        <property name="Second argument" required="Yes">The second int value.</property>
  +        <property name="nth argument" required="No">The nth int value.</property>
  +        <property name="last argument" required="Yes">A reference name for reusing the value
  +                computed by this function.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.5" name="_StringFromFile">
  +<description>
  +	<p>
  +	The StringFromFile function can be used to read strings from a text file. 
  +	This is useful for running tests that require lots of variable data.
  +	For example when testing a banking application, 100s or 1000s of different account numbers might be required.
  +	</p>
  +	<p>
  +	Each time it is called it reads the next line from the file.
  +	When the end of the file is reached, it will start reading again from the beginning.
  +	If there are multiple references to the function in a test script, each will open the file independently,
  +	even if the file names are the same.
  +	[If the value is to be used again elsewhere, use different variable names for each function call.]
  +	</p>
  +	<p>If an error occurs opening or reading the file, then the function returns the string "**ERR**"</p>
  +</description>
  +
  +<properties>
  +        <property name="First argument" required="Yes">Path to the file name.
  +        	(The path can be relative to the JMeter launch directory)
  +        </property>
  +        <property name="Second argument" required="No">
  +A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}.
  +        </property>
  +</properties>
  +<p>The file name parameter is resolved when the file is opened or re-opened.</p>
  +<p>The reference name parameter (if supplied) is resolved every time the function is executed.</p>
  +</component>
  +
  +<component index="14.5.6" name="__machineName">
  +<description><p>The machineName function returns the local host name</p></description>
  +
  +<properties>
  +        <property name="Name of function" required="Yes">A reference name for reusing the value
  +                computed by this function.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.7" name="__javaScript">
  +<description><p>The javaScript function executes a piece of JavaScript (not Java!) code and returns its value</p>
  +	</description>
  +
  +<properties>
  +        <property name="Expression" required="Yes">The JavaScript expression to be executed. For example:
  +        	<ul>
  +        		<li>new Date() - return the current date and time</li>
  +        		<li>Math.floor(Math.random()*(${maxRandom}+1))
  +        			- a random number between 0 and the variable maxRandom</li>
  +        		<li>${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1))
  +        			- a random number between the variables minRandom and maxRandom</li>
  +        	</ul>
  +        	</property>
  +        <property name="Name of function" required="Yes">A reference name for reusing the value
  +                computed by this function.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.8" name="__Random">
  +<description><p>The random function returns a random number that lies between the given min and max values.</p></description>
  +
  +<properties>
  +        <property name="Minimum value" required="Yes">A number</property>
  +        <property name="Maximum value" required="Yes">A bigger number</property>
  +        <property name="Name of function" required="Yes">A reference name for reusing the value
  +                computed by this function.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.8" name="__CSVRead">
  +<description><p>The CSVFile function returns a string from a CSV file (c.f. <a href="#_StringFromFile">StringFromFile</a>)</p>
  +	<p>NOTE: A single instance of the file is opened and used for all threads.</p></description>
  +
  +<properties>
  +        <property name="File Name" required="Yes">The file to read from</property>
  +        <property name="Column number" required="Yes">
  +        	The column number in the file.
  +        	0 = first column, 1 = second etc.
  +        	"next" - go to next line of file.
  +        	</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.9" name="__property">
  +<description><p>The property function returns the value of a JMeter property. 
  +	If the property value cannot be found, and no default has been supplied, it returns the property name.
  +	When supplying a default value, there is no need to provide a function name - the parameter can be set to null, and it will be ignored.
  +	</p>For example:<p>
  +<code>
  +<pre>
  +${__property(user.dir)} - return value of user.dir
  +${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR
  +${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD
  +${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it
  +</pre>
  +</code></p>
  +	</description>
  +
  +<properties>
  +        <property name="Property Name" required="Yes">The property name to be retrieved.</property>
  +        <property name="Name of function" required="No">A reference name for reusing the value
  +                computed by this function.</property>
  +        <property name="Default Value" required="No">The default value for the property.</property>
  +</properties>
  +</component>
  +
  +<component index="14.5.10" name="__P">
  +<description><p>This is a simplified property function which is
  +	intended for use with properties defined on the command line.
  +	If the property is not found, the default is returned.
  +	If no default was provided, then returns 1.
  +	</p>For example:<p>
  +<code>
  +<pre>
  +Define the property value:
  +
  +jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu
  +
  +Fetch the values:
  +${__P(group1.threads)} - return the value of group1.threads
  +${__P(group1.loops)} - return the value of group1.loops
  +${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined
  +</pre>
  +In the examples above, the first function call would return 7, 
  +the second would return 1 and the last would return www.dummy.org
  +(unless those properties were defined elsewhere!)
  +</code></p>
  +	</description>
  +
  +<properties>
  +        <property name="Property Name" required="Yes">The property name to be retrieved.</property>
  +        <property name="Default Value" required="No">The default value for the property.
  +        	If omitted, the default is set to "1".</property>
  +</properties>
  +</component>
  +
  +</subsection>
  +
   </section>
   
   </body>
  
  
  
  1.56      +1 -227    jakarta-jmeter/xdocs/usermanual/component_reference.xml
  
  Index: component_reference.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-jmeter/xdocs/usermanual/component_reference.xml,v
  retrieving revision 1.55
  retrieving revision 1.56
  diff -u -r1.55 -r1.56
  --- component_reference.xml	8 Oct 2003 00:04:16 -0000	1.55
  +++ component_reference.xml	8 Oct 2003 18:49:41 -0000	1.56
  @@ -1361,232 +1361,6 @@
   </component>
   </section>
   
  -<section name="13.10 Functions" anchor="functions">
  -<p>Please read the <a href="functions.html">general description</a> of how functions work.  Here is given only the details of
  -specific functions.</p>
  -
  -<component index="13.10.1" name="__regexFunction">
  -<description><p>The Regex Function is used to parse the previous response using any regular
  -expression (provided by user).  The function returns the template string with variable values filled
  -in.</p>
  -<p>The __regexFunction stores values for future use.  In the sixth parameter, you can specify
  -a reference name.  After this function executes, the same values can be retrieved at later times
  -using the syntax for user-defined values.  For instance, if you enter "refName" as the sixth
  -parameter you will be able to use:
  -<ul>
  -<li>${refName} to refer to the computed result of the second parameter ("Template for the
  -replacement string") parsed by this function</li>
  -<li>${refName_g0} to refer to the entire match  parsed by this function.</li>
  -<li>${refName_g1} to refer to the first group parsed by this function.</li>
  -<li>${refName_g#} to refer to the n<sup>th</sup> group parsed by this function.</li>
  -</ul>
  -</p></description>
  -
  -<properties>
  -        <property name="First arguement" required="Yes">The first argument is the regular expression
  -        to be applied to the response data.  It will grab all matches.  Any parts of this expression
  -        that you wish to use in your template string, be sure to surround in parentheses.  Example:
  -        &amp;lt;a href="(.*)"&amp;gt;.  This will grab the value of the link and store it as the first group (there is
  -        only 1 group).  Another example: &amp;lt;input type="hidden" name="(.*)" value="(.*)"&amp;gt;.  This will
  -        grab the name as the first group, and the value as the second group.  These values can be used
  -        in your template string</property>
  -        <property name="Second argument" required="Yes">This is the template string that will replace
  -        the function at run-time.  To refer to a group captured in the regular expression, use the syntax:
  -        $[group_number]$.  Ie: $1$, or $2$.  Your template can be any string.</property>
  -        <property name="Third argument" required="Yes">The third argument tells JMeter which match
  -        to use.  Your regular expression might find numerous matches.  You have four choices:
  -                <ul><li>An integer - Tells JMeter to use that match.  '1' for the first found match, '2' for the
  -                second, and so on</li>
  -                <li>RAND - Tells JMeter to choose a match at random.</li>
  -                <li>ALL - Tells JMeter to use all matches, and create a template string for each one and then
  -                append them all together.  This option is little used.</li>
  -                <li>A float number between 0 and 1 - tells JMeter to find the Xth match using the formula:
  -                (number_of_matches_found * float_number) rounded to nearest integer.</li>
  -                </ul></property>
  -        <property name="Fourth argument" required="No">If 'ALL' was selected for the above argument
  -        value, then this argument will be inserted between each appended copy of the template value.</property>
  -        <property name="Fifth argument" required="No">Default value returned if no match is found</property>
  -    <property name="Sixth argument" required="No">A reference name for reusing the values parsed by this function.<br></br>
  -        Stored values are ${refName} (the replacement template string) and ${refName_g#} where "#" is the
  -        group number from the regular expression ("0" can be used to refer to the entire match).</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.2" name="__counter">
  -<description><p>The counter generates a new number each time it is called, starting with 1
  -and incrementing by +1 each time.  The counter can be configured to keep each simulated user's values
  -separate, or to use the same counter for all user.  If each user's values is incremented separately,
  -that is like counting the number of iterations through the test plan.  A global counter is like
  -counting how many times that request was run.</p></description>
  -
  -<properties>
  -        <property name="First argument" required="Yes">TRUE if you wish each simulated user's counter
  -        to be kept independent and separate from the other users.  FALSE for a global counter.</property>
  -
  -<property name="Second argument" required="No">A reference name for reusing the value created by this function.<br></br>
  -                Stored values are of the form ${refName}.  This allows you to keep one counter and refer to its value in
  -                multiple places.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.3" name="__threadNum">
  -<description><p>The thread number function simply returns the number of the thread currently
  -being executed.  These numbers are independent of ThreadGroup, meaning thread #1 in one threadgroup
  -is indistinguishable from thread #1 in another threadgroup, from the point of view of this function.</p>
  -
  -<p>There are no arguments for this function.</p>
  -</description>
  -</component>
  -
  -<component index="13.10.4" name="__intSum">
  -<description><p>The intsum function can be used to compute the sum of two or more integer values.
  -</p></description>
  -
  -<properties>
  -        <property name="First argument" required="Yes">The first int value.</property>
  -        <property name="Second argument" required="Yes">The second int value.</property>
  -        <property name="nth argument" required="No">The nth int value.</property>
  -        <property name="last argument" required="Yes">A reference name for reusing the value
  -                computed by this function.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.5" name="_StringFromFile">
  -<description>
  -	<p>
  -	The StringFromFile function can be used to read strings from a text file. 
  -	This is useful for running tests that require lots of variable data.
  -	For example when testing a banking application, 100s or 1000s of different account numbers might be required.
  -	</p>
  -	<p>
  -	Each time it is called it reads the next line from the file.
  -	When the end of the file is reached, it will start reading again from the beginning.
  -	If there are multiple references to the function in a test script, each will open the file independently,
  -	even if the file names are the same.
  -	[If the value is to be used again elsewhere, use different variable names for each function call.]
  -	</p>
  -	<p>If an error occurs opening or reading the file, then the function returns the string "**ERR**"</p>
  -</description>
  -
  -<properties>
  -        <property name="First argument" required="Yes">Path to the file name.
  -        	(The path can be relative to the JMeter launch directory)
  -        </property>
  -        <property name="Second argument" required="No">
  -A reference name - refName - for reusing the value created by this function. Stored values are of the form ${refName}.
  -        </property>
  -</properties>
  -<p>The file name parameter is resolved when the file is opened or re-opened.</p>
  -<p>The reference name parameter (if supplied) is resolved every time the function is executed.</p>
  -</component>
  -
  -<component index="13.10.6" name="__machineName">
  -<description><p>The machineName function returns the local host name</p></description>
  -
  -<properties>
  -        <property name="Name of function" required="Yes">A reference name for reusing the value
  -                computed by this function.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.7" name="__javaScript">
  -<description><p>The javaScript function executes a piece of JavaScript (not Java!) code and returns its value</p>
  -	</description>
  -
  -<properties>
  -        <property name="Expression" required="Yes">The JavaScript expression to be executed. For example:
  -        	<ul>
  -        		<li>new Date() - return the current date and time</li>
  -        		<li>Math.floor(Math.random()*(${maxRandom}+1))
  -        			- a random number between 0 and the variable maxRandom</li>
  -        		<li>${minRandom}+Math.floor(Math.random()*(${maxRandom}-${minRandom}+1))
  -        			- a random number between the variables minRandom and maxRandom</li>
  -        	</ul>
  -        	</property>
  -        <property name="Name of function" required="Yes">A reference name for reusing the value
  -                computed by this function.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.8" name="__Random">
  -<description><p>The random function returns a random number that lies between the given min and max values.</p></description>
  -
  -<properties>
  -        <property name="Minimum value" required="Yes">A number</property>
  -        <property name="Maximum value" required="Yes">A bigger number</property>
  -        <property name="Name of function" required="Yes">A reference name for reusing the value
  -                computed by this function.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.8" name="__CSVRead">
  -<description><p>The CSVFile function returns a string from a CSV file (c.f. <a href="#_StringFromFile">StringFromFile</a>)</p>
  -	<p>NOTE: A single instance of the file is opened and used for all threads.</p></description>
  -
  -<properties>
  -        <property name="File Name" required="Yes">The file to read from</property>
  -        <property name="Column number" required="Yes">
  -        	The column number in the file.
  -        	0 = first column, 1 = second etc.
  -        	"next" - go to next line of file.
  -        	</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.9" name="__property">
  -<description><p>The property function returns the value of a JMeter property. 
  -	If the property value cannot be found, and no default has been supplied, it returns the property name.
  -	When supplying a default value, there is no need to provide a function name - the parameter can be set to null, and it will be ignored.
  -	</p>For example:<p>
  -<code>
  -<pre>
  -${__property(user.dir)} - return value of user.dir
  -${__property(user.dir,UDIR)} - return value of user.dir and save in UDIR
  -${__property(abcd,ABCD,atod)} - return value of property abcd (or "atod" if not defined) and save in ABCD
  -${__property(abcd,,atod)} - return value of property abcd (or "atod" if not defined) but don't save it
  -</pre>
  -</code></p>
  -	</description>
  -
  -<properties>
  -        <property name="Property Name" required="Yes">The property name to be retrieved.</property>
  -        <property name="Name of function" required="No">A reference name for reusing the value
  -                computed by this function.</property>
  -        <property name="Default Value" required="No">The default value for the property.</property>
  -</properties>
  -</component>
  -
  -<component index="13.10.10" name="__P">
  -<description><p>This is a simplified property function which is
  -	intended for use with properties defined on the command line.
  -	If the property is not found, the default is returned.
  -	If no default was provided, then returns 1.
  -	</p>For example:<p>
  -<code>
  -<pre>
  -Define the property value:
  -
  -jmeter -Jgroup1.threads=7 -Jhostname1=www.realhost.edu
  -
  -Fetch the values:
  -${__P(group1.threads)} - return the value of group1.threads
  -${__P(group1.loops)} - return the value of group1.loops
  -${__P(hostname,www.dummy.org)} - return value of property hostname or www.dummy.org if not defined
  -</pre>
  -In the examples above, the first function call would return 7, 
  -the second would return 1 and the last would return www.dummy.org
  -(unless those properties were defined elsewhere!)
  -</code></p>
  -	</description>
  -
  -<properties>
  -        <property name="Property Name" required="Yes">The property name to be retrieved.</property>
  -        <property name="Default Value" required="No">The default value for the property.
  -        	If omitted, the default is set to "1".</property>
  -</properties>
  -</component>
  -
  -</section>
   </body>
   </document>
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: jmeter-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: jmeter-dev-help@jakarta.apache.org