<commit_before><?xml version="1.0"?>
<!--
   Copyright 2001-2006 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<!DOCTYPE document
[
<!ENTITY sect-num '19'>
]>

<document prev="component_reference.html" next="regular_expressions.html" date="2004/06/12">

<properties>
  <title>User's Manual: Functions</title>
</properties>

<body>

<!--
	Because this is an XML document, all tags must be properly closed, including ones
	which are passed unchanged into the HTML output, e.g. <br/>, not just <br>.
	
	Unfortunately Java does not currently allow for this - it outputs the trailing > -
	which messes up the Help display. 
	To avoid these artefacts, use the form <br></br>, which Java does seem to handle OK.

 -->

<section name="&sect-num;. Functions" anchor="functions">
<p>
JMeter functions are special values that can populate fields of any Sampler or other configuration
element in a test tree.  A function call looks like this:</p>

<p><code>${__functionName(var1,var2,var3)}</code></p>

<p>
Where "__functionName" matches the name of a function.
<br></br>
Parentheses surround the parameters sent to the function, for example ${__time(YMD)}
The actual parameters vary from function to function.  
Functions that require no parameters can leave off the parentheses, for example ${__threadNum}.
</p>

<p>List of functions:</p>
<ul>
        <li><a href="#__regexFunction">regexFunction - regular expression evaluator</a></li>
        <li><a href="#__counter">counter</a></li>
        <li><a href="#__threadNum">threadNum - get thread number</a></li>
        <li><a href="#__intSum">intSum - add variables</a></li>
        <li><a href="#__StringFromFile">StringFromFile - read a line from a file</a></li>
        <li><a href="#__machineName">machineName - get the local machine name</a></li>
        <li><a href="#__javaScript">JavaScript (Apache Rhino)</a></li>
        <li><a href="#__Random">random number</a></li>
        <li><a href="#__CSVRead">CSVRead - read from CSV delimited file</a></li>
        <li><a href="#__property">read a property</a></li>
        <li><a href="#__P">P - read a property</a></li>
        <li><a href="#__setProperty">setProperty - set a property</a></li>
        <li><a href="#__log">log - log a message</a></li>
        <li><a href="#__logn">logn - log a message</a></li>
        <li><a href="#__BeanShell">BeanShell - run BeanShell</a></li>
        <li><a href="#__split">split - Split a string into variables</a></li>
        <li><a href="#__XPath">XPath - XPath use an xpath expression</a></li>
        <li><a href="#__time">time - return current time in various formats</a></li>
        <li><a href="#__jexl">jexl - evaluate a Commons Jexl expression</a></li>
</ul>

<subsection name="&sect-num;.1 What can functions do" anchor="what_can_do">
<p>There are two kinds of functions: user-defined static values (or variables), and built-in functions.<br></br>
User-defined static values allow the user to define variables to be replaced with their static value when
a test tree is compiled and submitted to be run.  This replacement happens once at the beginning of the test
run.  This could be used to replace the DOMAIN field of all HTTP requests, for example - making it a simple 
matter to change a test to target a different server with the same test.
</p>
<p>This type of replacement is possible without functions, but was less convenient and less intuitive.
It required users to create default config elements that would fill in blank values of Samplers.  User-defined
functions allow one to replace only part of any given value, not just filling in blank values.</p>
<p>
With built-in functions users can compute new values at run-time based on previous response data, which
thread the function is in, the time, and many other sources.  These values are generated fresh for every
request throughout the course of the test. </p>
<note>Functions are shared between threads. 
Each occurrence of a function call in a test plan is handled by a separate function instance.</note>
</subsection>

<subsection name="&sect-num;.2 Where can functions be used?" anchor="where">
<p>A user-defined function can be written into any field of any test component.  Some fields do not allow random strings 
because they are expecting numbers, and thus will not accept a function.  However, most fields will allow
functions.</p>
<p>Built-in functions can be written into any field of non-controller test components. This includes
Samplers, Timers, Listeners, Modifiers, Assertions, Pre-Processors, Post-Processors and Config Elements.</p>
<note>When using variable/function references in SQL code (etc),
remember to include any necessary quotes for text strings,
i.e. use<br></br>
SELECT item from table where name='${VAR}'
<br></br><b>not</b>
<br></br>
SELECT item from table where name=${VAR}
<br></br>(unless VAR itself contains the quotes)
</note>
</subsection>

<subsection name="&sect-num;.3 Writing the function string" anchor="how">
<p>User-defined functions take the form: <code>${varName}</code>.  In the TestPlan tree element, a two-column table
of user-defined values is kept, matching up variable names with static values.  Referencing the
variable in a test element is done by bracketing the variable name with '${' and '}'.</p>
<p>Built-in functions are written in the same manner, but by convention, the names of built-in
parameters begin with "__" to avoid conflict with user value names<sup>*</sup>.  Some functions take arguments to
configure them, and these go in parentheses, comma-delimited.  If the function takes no arguments, the parentheses can
be left out.  A further complication for argument values that themselves contain commas is that the value
should be escaped as necessary.  Thus, if you need to include a comma in your parameter value, escape it like so: '\,'.  JMeter provides a tool to help you construct
function calls for various built-in functions, which you can then copy-paste.  It will not automatically escape values for you, since functions can be parameters to other functions, and you should only escape values you intend as literal.</p>
<note><sup>*</sup>If you define a user-defined static variable with the same name as a built-in function, your static
variable will override the built-in function.</note>
</subsection>
<commit_msg>Bug 39861 - fix typo<commit_after><?xml version="1.0"?>
<!--
   Copyright 2001-2006 The Apache Software Foundation
 
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
       http://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<!DOCTYPE document
[
<!ENTITY sect-num '19'>
]>

<document prev="component_reference.html" next="regular_expressions.html" date="2004/06/12">

<properties>
  <title>User's Manual: Functions</title>
</properties>

<body>

<!--
	Because this is an XML document, all tags must be properly closed, including ones
	which are passed unchanged into the HTML output, e.g. <br/>, not just <br>.
	
	Unfortunately Java does not currently allow for this - it outputs the trailing > -
	which messes up the Help display. 
	To avoid these artefacts, use the form <br></br>, which Java does seem to handle OK.

 -->

<section name="&sect-num;. Functions" anchor="functions">
<p>
JMeter functions are special values that can populate fields of any Sampler or other configuration
element in a test tree.  A function call looks like this:</p>

<p><code>${__functionName(var1,var2,var3)}</code></p>

<p>
Where "__functionName" matches the name of a function.
<br></br>
Parentheses surround the parameters sent to the function, for example ${__time(YMD)}
The actual parameters vary from function to function.  
Functions that require no parameters can leave off the parentheses, for example ${__threadNum}.
</p>

<p>List of functions:</p>
<ul>
        <li><a href="#__regexFunction">regexFunction - regular expression evaluator</a></li>
        <li><a href="#__counter">counter</a></li>
        <li><a href="#__threadNum">threadNum - get thread number</a></li>
        <li><a href="#__intSum">intSum - add variables</a></li>
        <li><a href="#__StringFromFile">StringFromFile - read a line from a file</a></li>
        <li><a href="#__machineName">machineName - get the local machine name</a></li>
        <li><a href="#__javaScript">JavaScript (Apache Rhino)</a></li>
        <li><a href="#__Random">random number</a></li>
        <li><a href="#__CSVRead">CSVRead - read from CSV delimited file</a></li>
        <li><a href="#__property">read a property</a></li>
        <li><a href="#__P">P - read a property</a></li>
        <li><a href="#__setProperty">setProperty - set a property</a></li>
        <li><a href="#__log">log - log a message</a></li>
        <li><a href="#__logn">logn - log a message</a></li>
        <li><a href="#__BeanShell">BeanShell - run BeanShell</a></li>
        <li><a href="#__split">split - Split a string into variables</a></li>
        <li><a href="#__XPath">XPath - XPath use an xpath expression</a></li>
        <li><a href="#__time">time - return current time in various formats</a></li>
        <li><a href="#__jexl">jexl - evaluate a Commons Jexl expression</a></li>
</ul>

<subsection name="&sect-num;.1 What can functions do" anchor="what_can_do">
<p>There are two kinds of functions: user-defined static values (or variables), and built-in functions.<br></br>
User-defined static values allow the user to define variables to be replaced with their static value when
a test tree is compiled and submitted to be run.  This replacement happens once at the beginning of the test
run.  This could be used to replace the DOMAIN field of all HTTP requests, for example - making it a simple 
matter to change a test to target a different server with the same test.
</p>
<p>This type of replacement is possible without functions, but was less convenient and less intuitive.
It required users to create default config elements that would fill in blank values of Samplers.  User-defined
functions allow one to replace only part of any given value, not just filling in blank values.</p>
<p>
With built-in functions users can compute new values at run-time based on previous response data, which
thread the function is in, the time, and many other sources.  These values are generated fresh for every
request throughout the course of the test. </p>
<note>Functions are shared between threads. 
Each occurrence of a function call in a test plan is handled by a separate function instance.</note>
</subsection>

<subsection name="&sect-num;.2 Where can functions be used?" anchor="where">
<p>A user-defined function can be written into any field of any test component.  Some fields do not allow random strings 
because they are expecting numbers, and thus will not accept a function.  However, most fields will allow
functions.</p>
<p>Built-in functions can be written into any field of non-controller test components. This includes
Samplers, Timers, Listeners, Modifiers, Assertions, Pre-Processors, Post-Processors and Config Elements.</p>
<note>When using variable/function references in SQL code (etc),
remember to include any necessary quotes for text strings,
i.e. use<br></br>
SELECT item from table where name='${VAR}'
<br></br><b>not</b>
<br></br>
SELECT item from table where name=${VAR}
<br></br>(unless VAR itself contains the quotes)
</note>
</subsection>

<subsection name="&sect-num;.3 Writing the function string" anchor="how">
<p>User-defined functions take the form: <code>${varName}</code>.  In the TestPlan tree element, a two-column table
of user-defined values is kept, matching up variable names with static values.  Referencing the
variable in a test element is done by bracketing the variable name with '${' and '}'.</p>
<p>Built-in functions are written in the same manner, but by convention, the names of built-in
functions begin with "__" to avoid conflict with user value names<sup>*</sup>.  Some functions take arguments to
configure them, and these go in parentheses, comma-delimited.  If the function takes no arguments, the parentheses can
be left out.  A further complication for argument values that themselves contain commas is that the value
should be escaped as necessary.  Thus, if you need to include a comma in your parameter value, escape it like so: '\,'.  JMeter provides a tool to help you construct
function calls for various built-in functions, which you can then copy-paste.  It will not automatically escape values for you, since functions can be parameters to other functions, and you should only escape values you intend as literal.</p>
<note><sup>*</sup>If you define a user-defined static variable with the same name as a built-in function, your static
variable will override the built-in function.</note>
</subsection>

{'fraction_non_alphanumeric': 0.1065800992121389, 'fraction_numerical': 0.004741756638459294, 'mean_word_length': 4.196739954510993, 'pattern_counts': {'":': 0, '<': 303, '<?xml version=': 2, '>': 305, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4772378', 'n_tokens_mistral': 3796, 'n_tokens_neox': 3688, 'n_words': 1735}