1cdf0e10cSrcweir<?xml version="1.0" encoding="UTF-8"?> 2cdf0e10cSrcweir 3cdf0e10cSrcweir 4cdf0e10cSrcweir 5*d33d0967SAndrew Rist<!--*********************************************************** 6*d33d0967SAndrew Rist * 7*d33d0967SAndrew Rist * Licensed to the Apache Software Foundation (ASF) under one 8*d33d0967SAndrew Rist * or more contributor license agreements. See the NOTICE file 9*d33d0967SAndrew Rist * distributed with this work for additional information 10*d33d0967SAndrew Rist * regarding copyright ownership. The ASF licenses this file 11*d33d0967SAndrew Rist * to you under the Apache License, Version 2.0 (the 12*d33d0967SAndrew Rist * "License"); you may not use this file except in compliance 13*d33d0967SAndrew Rist * with the License. You may obtain a copy of the License at 14*d33d0967SAndrew Rist * 15*d33d0967SAndrew Rist * http://www.apache.org/licenses/LICENSE-2.0 16*d33d0967SAndrew Rist * 17*d33d0967SAndrew Rist * Unless required by applicable law or agreed to in writing, 18*d33d0967SAndrew Rist * software distributed under the License is distributed on an 19*d33d0967SAndrew Rist * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 20*d33d0967SAndrew Rist * KIND, either express or implied. See the License for the 21*d33d0967SAndrew Rist * specific language governing permissions and limitations 22*d33d0967SAndrew Rist * under the License. 23*d33d0967SAndrew Rist * 24*d33d0967SAndrew Rist ***********************************************************--> 25*d33d0967SAndrew Rist 26*d33d0967SAndrew Rist 27cdf0e10cSrcweir 28cdf0e10cSrcweir 29cdf0e10cSrcweir <helpdocument version="1.0"> 30cdf0e10cSrcweir<meta> 31cdf0e10cSrcweir<topic id="textsbasicshared01020300xml" indexer="include" status="PUBLISH"> 32cdf0e10cSrcweir<title id="tit" xml-lang="en-US">Using Procedures and Functions</title> 33cdf0e10cSrcweir<filename>/text/sbasic/shared/01020300.xhp</filename> 34cdf0e10cSrcweir</topic> 35cdf0e10cSrcweir</meta> 36cdf0e10cSrcweir<body> 37cdf0e10cSrcweir<section id="prozedur"> 38cdf0e10cSrcweir<bookmark xml-lang="en-US" branch="index" id="bm_id3149456"><bookmark_value>procedures</bookmark_value> 39cdf0e10cSrcweir<bookmark_value>functions;using</bookmark_value> 40cdf0e10cSrcweir<bookmark_value>variables;passing to procedures and functions</bookmark_value> 41cdf0e10cSrcweir<bookmark_value>parameters;for procedures and functions</bookmark_value> 42cdf0e10cSrcweir<bookmark_value>parameters;passing by reference or value</bookmark_value> 43cdf0e10cSrcweir<bookmark_value>variables;scope</bookmark_value> 44cdf0e10cSrcweir<bookmark_value>scope of variables</bookmark_value> 45cdf0e10cSrcweir<bookmark_value>GLOBAL variables</bookmark_value> 46cdf0e10cSrcweir<bookmark_value>PUBLIC variables</bookmark_value> 47cdf0e10cSrcweir<bookmark_value>PRIVATE variables</bookmark_value> 48cdf0e10cSrcweir<bookmark_value>functions;return value type</bookmark_value> 49cdf0e10cSrcweir<bookmark_value>return value type of functions</bookmark_value> 50cdf0e10cSrcweir</bookmark> 51cdf0e10cSrcweir<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> 52cdf0e10cSrcweir<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> 53cdf0e10cSrcweir</section> 54cdf0e10cSrcweir<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> 55cdf0e10cSrcweir 56cdf0e10cSrcweir<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> 57cdf0e10cSrcweir 58cdf0e10cSrcweir<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> 59cdf0e10cSrcweir<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> 60cdf0e10cSrcweir<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> 61cdf0e10cSrcweir<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> 62cdf0e10cSrcweir<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> 63cdf0e10cSrcweir<paragraph role="code" id="par_id3151114" xml-lang="en-US" l10n="U" oldref="29">Program code</paragraph> 64cdf0e10cSrcweir<paragraph role="code" id="par_id3146975" xml-lang="en-US" l10n="U" oldref="30">END SUB</paragraph> 65cdf0e10cSrcweir<paragraph role="paragraph" id="par_id3152577" xml-lang="en-US" l10n="U" oldref="31">The SUB is called using the following syntax:</paragraph> 66cdf0e10cSrcweir<paragraph role="code" id="par_id3159154" xml-lang="en-US" l10n="U" oldref="32">SubName(Value1, Value2,...)</paragraph> 67cdf0e10cSrcweir<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> 68cdf0e10cSrcweir<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> 69cdf0e10cSrcweir<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> 70cdf0e10cSrcweir<paragraph role="code" id="par_id3156284" xml-lang="en-US" l10n="U" oldref="36">Program code</paragraph> 71cdf0e10cSrcweir<paragraph role="code" id="par_id3145799" xml-lang="en-US" l10n="U" oldref="37"> 72cdf0e10cSrcweir<emph>FunctionName=Result</emph> 73cdf0e10cSrcweir</paragraph> 74cdf0e10cSrcweir<paragraph role="code" id="par_id3150716" xml-lang="en-US" l10n="U" oldref="38">End Function</paragraph> 75cdf0e10cSrcweir<paragraph role="paragraph" id="par_id3153839" xml-lang="en-US" l10n="U" oldref="39">The FUNCTION is called using the following syntax:</paragraph> 76cdf0e10cSrcweir<paragraph role="code" id="par_id3146914" xml-lang="en-US" l10n="U" oldref="40">Variable=FunctionName(Parameter1, Parameter2,...)</paragraph> 77cdf0e10cSrcweir<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/> 78cdf0e10cSrcweir<item type="literal">Library.Module.Macro()</item> 79cdf0e10cSrcweir<br/> For example, to call the Autotext macro from the Gimmicks library, use the following command:<br/> 80cdf0e10cSrcweir<item type="literal">Gimmicks.AutoText.Main()</item> 81cdf0e10cSrcweir</paragraph> 82cdf0e10cSrcweir<paragraph role="heading" id="hd_id3156276" xml-lang="en-US" level="2" l10n="U" oldref="45">Passing Variables by Value or Reference</paragraph> 83cdf0e10cSrcweir<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> 84cdf0e10cSrcweir<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> 85cdf0e10cSrcweir<paragraph role="code" id="par_id3150042" xml-lang="en-US" l10n="U" oldref="54">Result = Function(<emph>ByVal</emph> Parameter)</paragraph> 86cdf0e10cSrcweir<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> 87cdf0e10cSrcweir<paragraph role="heading" id="hd_id3150982" xml-lang="en-US" level="2" l10n="U" oldref="57">Scope of Variables</paragraph> 88cdf0e10cSrcweir<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> 89cdf0e10cSrcweir<paragraph role="heading" id="hd_id3154186" xml-lang="en-US" level="3" l10n="U" oldref="59">Declaring Variables Outside a SUB or FUNCTION</paragraph> 90cdf0e10cSrcweir<paragraph role="code" id="par_id3150208" xml-lang="en-US" l10n="CHG" oldref="111">GLOBAL VarName As TYPENAME</paragraph> 91cdf0e10cSrcweir<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> 92cdf0e10cSrcweir<paragraph role="code" id="par_id3153198" xml-lang="en-US" l10n="CHG" oldref="60">PUBLIC VarName As TYPENAME</paragraph> 93cdf0e10cSrcweir<paragraph role="paragraph" id="par_id3150088" xml-lang="en-US" l10n="U" oldref="61">The variable is valid in all modules.</paragraph> 94cdf0e10cSrcweir<paragraph role="code" id="par_id3158212" xml-lang="en-US" l10n="CHG" oldref="62">PRIVATE VarName As TYPENAME</paragraph> 95cdf0e10cSrcweir<paragraph role="paragraph" id="par_id3152994" xml-lang="en-US" l10n="U" oldref="63">The variable is only valid in this module.</paragraph> 96cdf0e10cSrcweir<paragraph role="code" id="par_id3150886" xml-lang="en-US" l10n="U" oldref="64">DIM VarName As TYPENAME</paragraph> 97cdf0e10cSrcweir<paragraph role="paragraph" id="par_id3150368" xml-lang="en-US" l10n="U" oldref="65">The variable is only valid in this module.</paragraph> 98cdf0e10cSrcweir<paragraph role="heading" id="hd_id5097506" xml-lang="en-US" level="3" l10n="NEW">Example for private variables</paragraph> 99cdf0e10cSrcweir<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> 100cdf0e10cSrcweir<paragraph role="code" id="par_id2042298" xml-lang="en-US" l10n="NEW">Private myText As String</paragraph> 101cdf0e10cSrcweir<paragraph role="code" id="par_id2969756" xml-lang="en-US" l10n="NEW">Sub initMyText</paragraph> 102cdf0e10cSrcweir<paragraph role="code" id="par_id9475997" xml-lang="en-US" l10n="NEW">myText = "Hello"</paragraph> 103cdf0e10cSrcweir<paragraph role="code" id="par_id6933500" xml-lang="en-US" l10n="NEW">print "in module1 : ", myText</paragraph> 104cdf0e10cSrcweir<paragraph role="code" id="par_id631733" xml-lang="en-US" l10n="NEW">End Sub</paragraph> 105cdf0e10cSrcweir<paragraph role="code" id="par_id8234199" xml-lang="en-US" l10n="NEW">REM ***** Module2 *****</paragraph> 106cdf0e10cSrcweir<paragraph role="code" id="par_id6969512" xml-lang="en-US" l10n="NEW">'Option Explicit</paragraph> 107cdf0e10cSrcweir<paragraph role="code" id="par_id1196935" xml-lang="en-US" l10n="NEW">Sub demoBug</paragraph> 108cdf0e10cSrcweir<paragraph role="code" id="par_id1423993" xml-lang="en-US" l10n="NEW">CompatibilityMode( true )</paragraph> 109cdf0e10cSrcweir<paragraph role="code" id="par_id6308786" xml-lang="en-US" l10n="NEW">initMyText</paragraph> 110cdf0e10cSrcweir<paragraph role="code" id="par_id4104129" xml-lang="en-US" l10n="NEW">' Now returns empty string</paragraph> 111cdf0e10cSrcweir<paragraph role="code" id="par_id7906125" xml-lang="en-US" l10n="NEW">' (or rises error for Option Explicit)</paragraph> 112cdf0e10cSrcweir<paragraph role="code" id="par_id8055970" xml-lang="en-US" l10n="NEW">print "Now in module2 : ", myText</paragraph> 113cdf0e10cSrcweir<paragraph role="code" id="par_id2806176" xml-lang="en-US" l10n="NEW">End Sub</paragraph> 114cdf0e10cSrcweir<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> 115cdf0e10cSrcweir<paragraph role="code" id="par_id3156288" xml-lang="en-US" l10n="CHG" oldref="67">STATIC VarName As TYPENAME</paragraph> 116cdf0e10cSrcweir<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> 117cdf0e10cSrcweir<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> 118cdf0e10cSrcweir<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> 119cdf0e10cSrcweir<paragraph role="code" id="par_id3152899" xml-lang="en-US" l10n="U" oldref="43">Function WordCount(WordText as String) <emph>as Integer</emph> 120cdf0e10cSrcweir</paragraph> 121cdf0e10cSrcweir</body> 122cdf0e10cSrcweir</helpdocument> 123