1*b1cdbd2cSJim Jagielski<?xml version="1.0" encoding="UTF-8"?> 2*b1cdbd2cSJim Jagielski 3*b1cdbd2cSJim Jagielski 4*b1cdbd2cSJim Jagielski 5*b1cdbd2cSJim Jagielski<!--*********************************************************** 6*b1cdbd2cSJim Jagielski * 7*b1cdbd2cSJim Jagielski * Licensed to the Apache Software Foundation (ASF) under one 8*b1cdbd2cSJim Jagielski * or more contributor license agreements. See the NOTICE file 9*b1cdbd2cSJim Jagielski * distributed with this work for additional information 10*b1cdbd2cSJim Jagielski * regarding copyright ownership. The ASF licenses this file 11*b1cdbd2cSJim Jagielski * to you under the Apache License, Version 2.0 (the 12*b1cdbd2cSJim Jagielski * "License"); you may not use this file except in compliance 13*b1cdbd2cSJim Jagielski * with the License. You may obtain a copy of the License at 14*b1cdbd2cSJim Jagielski * 15*b1cdbd2cSJim Jagielski * http://www.apache.org/licenses/LICENSE-2.0 16*b1cdbd2cSJim Jagielski * 17*b1cdbd2cSJim Jagielski * Unless required by applicable law or agreed to in writing, 18*b1cdbd2cSJim Jagielski * software distributed under the License is distributed on an 19*b1cdbd2cSJim Jagielski * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20*b1cdbd2cSJim Jagielski * KIND, either express or implied. See the License for the 21*b1cdbd2cSJim Jagielski * specific language governing permissions and limitations 22*b1cdbd2cSJim Jagielski * under the License. 23*b1cdbd2cSJim Jagielski * 24*b1cdbd2cSJim Jagielski ***********************************************************--> 25*b1cdbd2cSJim Jagielski 26*b1cdbd2cSJim Jagielski 27*b1cdbd2cSJim Jagielski 28*b1cdbd2cSJim Jagielski 29*b1cdbd2cSJim Jagielski <helpdocument version="1.0"> 30*b1cdbd2cSJim Jagielski<meta> 31*b1cdbd2cSJim Jagielski<topic id="textsbasicshared01020300xml" indexer="include" status="PUBLISH"> 32*b1cdbd2cSJim Jagielski<title id="tit" xml-lang="en-US">Using Procedures and Functions</title> 33*b1cdbd2cSJim Jagielski<filename>/text/sbasic/shared/01020300.xhp</filename> 34*b1cdbd2cSJim Jagielski</topic> 35*b1cdbd2cSJim Jagielski</meta> 36*b1cdbd2cSJim Jagielski<body> 37*b1cdbd2cSJim Jagielski<section id="prozedur"> 38*b1cdbd2cSJim Jagielski<bookmark xml-lang="en-US" branch="index" id="bm_id3149456"><bookmark_value>procedures</bookmark_value> 39*b1cdbd2cSJim Jagielski<bookmark_value>functions;using</bookmark_value> 40*b1cdbd2cSJim Jagielski<bookmark_value>variables;passing to procedures and functions</bookmark_value> 41*b1cdbd2cSJim Jagielski<bookmark_value>parameters;for procedures and functions</bookmark_value> 42*b1cdbd2cSJim Jagielski<bookmark_value>parameters;passing by reference or value</bookmark_value> 43*b1cdbd2cSJim Jagielski<bookmark_value>variables;scope</bookmark_value> 44*b1cdbd2cSJim Jagielski<bookmark_value>scope of variables</bookmark_value> 45*b1cdbd2cSJim Jagielski<bookmark_value>GLOBAL variables</bookmark_value> 46*b1cdbd2cSJim Jagielski<bookmark_value>PUBLIC variables</bookmark_value> 47*b1cdbd2cSJim Jagielski<bookmark_value>PRIVATE variables</bookmark_value> 48*b1cdbd2cSJim Jagielski<bookmark_value>functions;return value type</bookmark_value> 49*b1cdbd2cSJim Jagielski<bookmark_value>return value type of functions</bookmark_value> 50*b1cdbd2cSJim Jagielski</bookmark> 51*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3149456" xml-lang="en-US" level="1" l10n="U" oldref="1"><link href="text/sbasic/shared/01020300.xhp">Using Procedures and Functions</link></paragraph> 52*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3150767" xml-lang="en-US" l10n="U" oldref="2">The following describes the basic use of procedures and functions in $[officename] Basic.</paragraph> 53*b1cdbd2cSJim Jagielski</section> 54*b1cdbd2cSJim Jagielski<paragraph role="note" id="par_id3151215" xml-lang="en-US" l10n="U" oldref="56">When you create a new module, $[officename] Basic automatically inserts a SUB called "Main". This default name has nothing to do with the order or the starting point of a $[officename] Basic project. You can also safely rename this SUB.</paragraph> 55*b1cdbd2cSJim Jagielski 56*b1cdbd2cSJim Jagielski<paragraph role="note" id="par_id314756320" xml-lang="en-US" l10n="NEW">Some restrictions apply for the names of your public variables, subs, and functions. You must not use the same name as one of the modules of the same library.</paragraph> 57*b1cdbd2cSJim Jagielski 58*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3154124" xml-lang="en-US" l10n="U" oldref="3">Procedures (SUBS) and functions (FUNCTIONS) help you maintaining a structured overview by separating a program into logical pieces.</paragraph> 59*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3153193" xml-lang="en-US" l10n="CHG" oldref="4">One benefit of procedures and functions is that, once you have developed a program code containing task components, you can use this code in another project.</paragraph> 60*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3153770" xml-lang="en-US" level="2" l10n="U" oldref="26">Passing Variables to Procedures (SUB) and Functions (FUNCTION)</paragraph> 61*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3155414" xml-lang="en-US" l10n="U" oldref="27">Variables can be passed to both procedures and functions. The SUB or FUNCTION must be declared to expect parameters:</paragraph> 62*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3163710" xml-lang="en-US" l10n="U" oldref="28">SUB SubName(<emph>Parameter1 As Type, Parameter2 As Type,...</emph>)</paragraph> 63*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3151114" xml-lang="en-US" l10n="U" oldref="29">Program code</paragraph> 64*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3146975" xml-lang="en-US" l10n="U" oldref="30">END SUB</paragraph> 65*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3152577" xml-lang="en-US" l10n="U" oldref="31">The SUB is called using the following syntax:</paragraph> 66*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3159154" xml-lang="en-US" l10n="U" oldref="32">SubName(Value1, Value2,...)</paragraph> 67*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3147124" xml-lang="en-US" l10n="U" oldref="33">The parameters passed to a SUB must fit to those specified in the SUB declaration.</paragraph> 68*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3147397" xml-lang="en-US" l10n="U" oldref="34">The same process applies to FUNCTIONS. In addition, functions always return a function result. The result of a function is defined by assigning the return value to the function name:</paragraph> 69*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3149412" xml-lang="en-US" l10n="U" oldref="35">FUNCTION FunctionName(Parameter1 As Type, Parameter2 As Type,...) As Type</paragraph> 70*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3156284" xml-lang="en-US" l10n="U" oldref="36">Program code</paragraph> 71*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3145799" xml-lang="en-US" l10n="U" oldref="37"> 72*b1cdbd2cSJim Jagielski<emph>FunctionName=Result</emph> 73*b1cdbd2cSJim Jagielski</paragraph> 74*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3150716" xml-lang="en-US" l10n="U" oldref="38">End Function</paragraph> 75*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3153839" xml-lang="en-US" l10n="U" oldref="39">The FUNCTION is called using the following syntax:</paragraph> 76*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3146914" xml-lang="en-US" l10n="U" oldref="40">Variable=FunctionName(Parameter1, Parameter2,...)</paragraph> 77*b1cdbd2cSJim Jagielski<paragraph role="tip" id="par_idN107B3" xml-lang="en-US">You can also use the fully qualified name to call a procedure or function:<br/> 78*b1cdbd2cSJim Jagielski<item type="literal">Library.Module.Macro()</item> 79*b1cdbd2cSJim Jagielski<br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> 80*b1cdbd2cSJim Jagielski<item type="literal">Gimmicks.AutoText.Main()</item> 81*b1cdbd2cSJim Jagielski</paragraph> 82*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3156276" xml-lang="en-US" level="2" l10n="U" oldref="45">Passing Variables by Value or Reference</paragraph> 83*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3155765" xml-lang="en-US" l10n="U" oldref="47">Parameters can be passed to a SUB or a FUNCTION either by reference or by value. Unless otherwise specified, a parameter is always passed by reference. That means that a SUB or a FUNCTION gets the parameter and can read and modify its value.</paragraph> 84*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3145640" xml-lang="en-US" l10n="U" oldref="53">If you want to pass a parameter by value insert the key word "ByVal" in front of the parameter when you call a SUB or FUNCTION, for example:</paragraph> 85*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3150042" xml-lang="en-US" l10n="U" oldref="54">Result = Function(<emph>ByVal</emph> Parameter)</paragraph> 86*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3149258" xml-lang="en-US" l10n="U" oldref="55">In this case, the original content of the parameter will not be modified by the FUNCTION since it only gets the value and not the parameter itself.</paragraph> 87*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3150982" xml-lang="en-US" level="2" l10n="U" oldref="57">Scope of Variables</paragraph> 88*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3149814" xml-lang="en-US" l10n="CHG" oldref="58">A variable defined within a SUB or FUNCTION, only remains valid until the procedure is exited. This is known as a "local" variable. In many cases, you need a variable to be valid in all procedures, in every module of all libraries, or after a SUB or FUNCTION is exited.</paragraph> 89*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3154186" xml-lang="en-US" level="3" l10n="U" oldref="59">Declaring Variables Outside a SUB or FUNCTION</paragraph> 90*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3150208" xml-lang="en-US" l10n="CHG" oldref="111">GLOBAL VarName As TYPENAME</paragraph> 91*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3145258" xml-lang="en-US" l10n="U" oldref="112">The variable is valid as long as the $[officename] session lasts.</paragraph> 92*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3153198" xml-lang="en-US" l10n="CHG" oldref="60">PUBLIC VarName As TYPENAME</paragraph> 93*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3150088" xml-lang="en-US" l10n="U" oldref="61">The variable is valid in all modules.</paragraph> 94*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3158212" xml-lang="en-US" l10n="CHG" oldref="62">PRIVATE VarName As TYPENAME</paragraph> 95*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3152994" xml-lang="en-US" l10n="U" oldref="63">The variable is only valid in this module.</paragraph> 96*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3150886" xml-lang="en-US" l10n="U" oldref="64">DIM VarName As TYPENAME</paragraph> 97*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3150368" xml-lang="en-US" l10n="U" oldref="65">The variable is only valid in this module.</paragraph> 98*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id5097506" xml-lang="en-US" level="3" l10n="NEW">Example for private variables</paragraph> 99*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id8738975" xml-lang="en-US" l10n="NEW">Enforce private variables to be private across modules by setting CompatibilityMode(true).</paragraph><comment>from i17948, see i54894</comment><paragraph role="code" id="par_id146488" xml-lang="en-US" l10n="NEW">REM ***** Module1 *****</paragraph> 100*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id2042298" xml-lang="en-US" l10n="NEW">Private myText As String</paragraph> 101*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id2969756" xml-lang="en-US" l10n="NEW">Sub initMyText</paragraph> 102*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id9475997" xml-lang="en-US" l10n="NEW">myText = "Hello"</paragraph> 103*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id6933500" xml-lang="en-US" l10n="NEW">print "in module1 : ", myText</paragraph> 104*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id631733" xml-lang="en-US" l10n="NEW">End Sub</paragraph> 105*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id8234199" xml-lang="en-US" l10n="NEW">REM ***** Module2 *****</paragraph> 106*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id6969512" xml-lang="en-US" l10n="NEW">'Option Explicit</paragraph> 107*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id1196935" xml-lang="en-US" l10n="NEW">Sub demoBug</paragraph> 108*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id1423993" xml-lang="en-US" l10n="NEW">CompatibilityMode( true )</paragraph> 109*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id6308786" xml-lang="en-US" l10n="NEW">initMyText</paragraph> 110*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id4104129" xml-lang="en-US" l10n="NEW">' Now returns empty string</paragraph> 111*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id7906125" xml-lang="en-US" l10n="NEW">' (or rises error for Option Explicit)</paragraph> 112*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id8055970" xml-lang="en-US" l10n="NEW">print "Now in module2 : ", myText</paragraph> 113*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id2806176" xml-lang="en-US" l10n="NEW">End Sub</paragraph> 114*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3154368" xml-lang="en-US" level="3" l10n="U" oldref="66">Saving Variable Content after Exiting a SUB or FUNCTION</paragraph> 115*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3156288" xml-lang="en-US" l10n="CHG" oldref="67">STATIC VarName As TYPENAME</paragraph> 116*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3154486" xml-lang="en-US" l10n="U" oldref="68">The variable retains its value until the next time the FUNCTION or SUB is entered. The declaration must exist inside a SUB or a FUNCTION.</paragraph> 117*b1cdbd2cSJim Jagielski<paragraph role="heading" id="hd_id3155809" xml-lang="en-US" level="2" l10n="U" oldref="41">Specifying the Return Value Type of a FUNCTION</paragraph> 118*b1cdbd2cSJim Jagielski<paragraph role="paragraph" id="par_id3149404" xml-lang="en-US" l10n="U" oldref="42">As with variables, include a type-declaration character after the function name, or the type indicated by "As" and the corresponding key word at the end of the parameter list to define the type of the function's return value, for example:</paragraph> 119*b1cdbd2cSJim Jagielski<paragraph role="code" id="par_id3152899" xml-lang="en-US" l10n="U" oldref="43">Function WordCount(WordText as String) <emph>as Integer</emph> 120*b1cdbd2cSJim Jagielski</paragraph> 121*b1cdbd2cSJim Jagielski</body> 122*b1cdbd2cSJim Jagielski</helpdocument> 123