Commands & Syntax > Commands > Macro Flow Control >

Procedure BEGIN: - < proc_def_begin >() ... [Pro]

www.perfectkeyboard.com

 

Procedure BEGIN:
<proc_def_begin>(Identifier,Parameter)
Available in: Professional edition

This command defines begin of procedure. Procedure is a piece of macro code that can be called using "proc_call" command within the macro. Procedure can have any number of parameters. Procedures do not return a value but it is possible to pass results out of the procedure using reference parameters. Reference parameter contains name of the variable it references to. Enclose a parameter in between "&" characters to tell the procedure that the parameter is a reference (example: &parRefParam&).

Example: Let's have "proc_def_begin"(P1, "parParam1","&parRefParam&") and let's have procedure call "proc_call"(P1, "555", "vResult"). Now, any modification of parRefParam (that is is done within the P1 procedure) is actually done on vResult variable since the parRefParam references it.

Procedure parameter should starts with "par" prefix (for example, "parInputText"). This makes the parameter known (accessible) only locally within the procedure so that it does not conflict with other macro variables. Procedure local variables should start with "lpv" (Local Procedure Variable) prefix (for example, "lpvTemporaryVariable") for the same reason. It is not allowed to define procedure within other procedure (embedded "proc_def_begin"). The procedure definition must be ended by "proc_def_end" command.
When getting actual value of the referenced variable, it is necessary to enclose it to % (example: %parRefParam% provides actual value while just parRefParam provides name of the referenced variable).

 

#

Parameter name

Parameter description

1

Identifier

Unique name of the procedure. The name is used as a parameter in "proc_call" command to identify what procedure to call.

2

Parameter

Any number of parameters. Each parameter must be enclosed in between " character and parameters must be delimited by ,

Example: "parInputText","parTime","&parRefOutputText&"

 

Example (Macro Steps):

 

1

<#> <#> This example shows how to use procedures

2

Macro execution: ONLY COMMANDS

3

Procedure BEGIN: AddQuotes with parameters (parStringInput, &parStringOutput&)

4

Variable SET "parStringOutput="%parStringInput%"", Message text=""

5

Procedure END

6

Procedure BEGIN: ConvertToUpper with parameters (parStringInput,&parStringOutput&)

7

Variable OPERATION "STR_UPPER" (Variable for result = parStringOutput, Input text/variable = %parStringInput%, Parameter 1 = 2, Parameter 2 = , Parameter 3 = 0)

8

Procedure END

9

Variable SET "vMyText=", Message text="Insert text you want to convert to upper case and enclose to quotes:"

10

IF STRING _vCanceled==1

11

Macro EXIT

12

ENDIF

13

Procedure CALL: ConvertToUpper with parameters (%vMyText%, vMyText )

14

Procedure CALL: AddQuotes with parameters (%vMyText%, vMyText )

15

Message SHOW "Information" : "%vMyText%" (other parameters: x = -100, y = -100, Window title = Result, Buttons = OK, Timeout (seconds) = 0, Always on top = No).

Example (Plain Text):

 

<#> This example shows how to use procedures

<cmds>

<proc_def_begin>(AddQuotes,"parStringInput", "&parStringOutput&")

   <varset>("parStringOutput=%_vQuoteChar%%parStringInput%%_vQuoteChar%","")

<proc_def_end>

 

<proc_def_begin>(ConvertToUpper,"parStringInput","&parStringOutput&")

   <var_oper>(parStringOutput,"%parStringInput%",STR_UPPER,"2","", "0")

<proc_def_end>

 

<varset>("vMyText=","Insert text you want to convert to upper case and enclose to quotes:")

<if_str>("_vCanceled==1")<#>

<exitmacro><#>

<endif>

 

<proc_call>(ConvertToUpper,"%vMyText%", "vMyText" )

<proc_call>(AddQuotes,"%vMyText%", "vMyText" )

 

<msg>(-100,-100,"%vMyText%","Result",1,0,0,0)