#UTILITY (utility execution section) 

Top  Previous  Next

 

#UTILITY( name, description ) [, HLP( helpid ) ] [, WIZARD( procedure ) ]

#UTILITY

Begins a utility generation control.

name

The name of the #UTILITY which identifies it for the Template Registry. This must be a valid Clarion label.

description

A string constant describing the utility section.

HLP

Specifies on-line help is available.

helpid

A string constant containing the identifier to access the Help system. This may be either a Help keyword or "context string."

WIZARD

Specifies the #UTILITY is used as a Wizard to generate a procedure or a complete application.

procedure

A string constant containing the fully qualified name of the #PROCEDURE for which it is a WIZARD.

The #UTILITY statement marks the beginning of a utility execution control section. The section is terminated by the next Template Code Section (#PROGRAM, #MODULE, #PROCEDURE, #CONTROL, #CODE, #EXTENSION, #UTILITY, or #GROUP) statement. The Template statements contained in this section control the utility execution process. Multiple #UTILITY sections are allowed in a single Template set.

The #UTILITY section is very similar to the #APPLICATION section, in that it allows you to produce output from the application. The purpose of #UTILITY is to provide extensible supplemental utilities for such things as program documentation, or a tree diagram of procedure calls. The list of registered utilities appears in the Utilities menu in the Clarion for Windows environment. #UTILITY with the WIZARD attribute specifies it contains a #SHEET with #TABs that display one tab at a time, guiding the user through the prompts.

 

Example:

#UTILITY(ProcCallTree, 'Output procedure call tree')

 #CREATE(%Application & '.TRE')

Procedure Call Tree: for %Application

#INSERT(%DisplayTree, %FirstProcedure, '', '  ')

#CLOSE

#!***********************************************************

#GROUP(%DisplayTree, %ThisProc, %Level, %NextIndent)

 #FIX(%Procedure, %ThisProc)

%Level+-%ThisProc (%ProcedureTemplate)

 #FOR(%ProcedureCalled)

   #IF(INSTANCE(%ProcedureCalled) = ITEMS(%ProcedureCalled))

#INSERT(%DisplayTree, %ProcedureCalled, %Level & %NextIndent, '  ')

   #ELSE

#INSERT(%DisplayTree, %ProcedureCalled, %Level & %NextIndent, '| ')

   #ENDIF

 #ENDFOR

 

 

Use the %UtilityArguments symbol to assign optional parameters for the target #UTILITY.

 

Example:

 

#declare(%one)

#declare(%two)

#set(%one,extract(%UtilityArguments,'one',0))

#set(%two,extract(%UtilityArguments,'two',0))