SheerPower® 4GL
A Guide to the SheerPower Language
Previous Contents Index

3.4.1 Understanding variable "namespace" when using routines

It is a proven fact that short, simple "code chunks" are easiest to maintain -- and that 80% of software costs are in the maintenance of existing software. So, an excellent focus is to write short, simple "code chunks"---small, easy-to-maintain pieces of code.

SheerPower 4GL has powerful features that make it easy to write short, simple "code chunks":

Each variable in a program belongs to a "namespace". By default, they belong to a "namespace" called MAIN. So: 


  abc = 123 
  print abc

is the same as: 


  abc = 123 
  print main$abc

is the same as: 


  main$abc = 123 
  print abc

SheerPower 4GL supports both ROUTINES--- that use the MAIN "namespace" and PRIVATE ROUTINES---that have their own "namespace". For example: 


  routine show_display 
    abc = 123 
    print main$abc 
  end routine

In this ROUTINE, the variable "abc" belongs to the "namespace" of MAIN---sharing its variable names with the main program.

However in this PRIVATE ROUTINE: 


  private routine do_totals 
    abc = 123 
    print abc 
  end routine

the variable "abc" belongs to the "namespace" of "do_totals": 


  private routine do_totals 
    abc = 123 
    print do_totals$abc 
  end routine

Now, lets look at a more complex example:

Example 3-7 Namespace 

  abc = 123 
  do_totals 
  stop 
 
  private routine do_totals 
    abc = 999 
    print 'The DO_TOTALS version: '; abc 
    print 'The MAIN version     : '; main$abc 
  end routine 
 
  end

Unlike the default ROUTINE feature in SheePower, that is used to segment program code into small, simple, easy-to-maintain chunks of code---The PRIVATE ROUTINE feature is used primarily to write reusable routines that will be used in a number of different applications. Here is a simple PRIVATE ROUTINE that is used to write messages to a message file:

Example 3-8 Private Routine - Example 

  private routine write_message with msg 
    if msg_ch = 0 then open file msg_ch: name 'message.log', access output 
    print #msg_ch: time$; ' '; msg 
  end routine

WRITE_MESSAGE has a single named parameter called "msg". The first time WRITE_MESSAGE is called, msg_ch will be zero, so a new message.log file is created and msg_ch receives the channel#. Then WRITE_MESSAGE writes out the current time and the message.

This PRIVATE ROUTINE can be called from any application, without worrying about variable name conflicts. 


   write_message with msg "this is a test"

The PRIVATE routine feature of SheerPower 4GL is designed to assist in writing routines that will be used in a number of different programs. The routines can be written without having to be concerned with accidental variable name conflicts---because all variable names in PRIVATE routines have their own, private, "namespace".

3.4.2 More on Routines

Routines can be edited as a complete unit.

To execute a ROUTINE, name the routine or use the DISPATCH statement. For more information on the dispatch statement see Section 10.9, DISPATCH.

To pass data in and out of routines, see Section 3.5, Passing Optional Parameters to Routines.

See Appendix M, SheerPower and Program Segmentation for more on routines in SheerPower.

DESCRIPTION:

ROUTINES are used to simplify programming. Routines simplify programs by breaking them up into small manageable pieces. Routines can be used to organize the individual thoughts and concepts in the program. The smaller the routines, the more successful you will be in writing code.

Each routine should be under 25 lines in length. If the number of lines exceeds 25, it is an indication that the routine is becoming too complex. Please see Appendix A, Coding Principles and Standards for more information.

Routine names must contain at least one underscore '_' (i.e., print_statistics).

Example 3-9 Executing routines/subroutines by name 

  request_info                // call request_info routine from main logic section 
  stop 
  
  routine request_info 
    print 'Please enter in the required informaton' 
    print
    get_username                // call get_username subroutine 
  end routine
 
  routine get_username 
    input prompt 'Username: ': uname$ 
    if  _back or _exit  then exit routine
  end routine
 
 
Username: Tester    <---- Type in your name and press [Enter]

3.4.3 EXIT ROUTINE

FORMAT:


        EXIT ROUTINE

EXAMPLE:

Example 3-10 EXIT ROUTINE statement 

  get_username 
  end
 
  routine get_username 
    input prompt 'Username: ': uname$ 
    if  _back or _exit  then exit routine
    if  uname$ = ''  then repeat routine
  end routine
 
 
Username: exit       <---- type in 'exit'

PURPOSE:

The EXIT ROUTINE statement enables you to exit from the current routine.

DESCRIPTION:

Use EXIT ROUTINE statement when you need to exit a routine early. For example,before you reach the end statement.

3.4.4 REPEAT ROUTINE

FORMAT:


        REPEAT ROUTINE

EXAMPLE:

Example 3-11 REPEAT ROUTINE statement 

  get_username 
  end
 
  routine get_username 
    input prompt 'Username: ': uname$ 
    if  _back or _exit  then exit routine
    if  uname$ = ''  then repeat routine
  end routine
 
 
Username:          <---- press the [Enter]
Username: Sunny    <---- type in your name or 'exit'

PURPOSE:

The REPEAT ROUTINE statement enables you to repeat execution of the current routine.

DESCRIPTION:

When SheerPower executes the REPEAT ROUTINE statement, control is passed to the first statement following the routine statement.

3.5 Passing Optional Parameters to Routines

FORMAT:


ROUTINE routine_name [WITH input_param value [, input_param value, ...]] 
  [, RETURNING output_param varname [, output_param varname,...]] 
  [, PRIVATE varname,...]

3.5.1 Parameter Passing Using WITH and RETURNING

EXAMPLE:

Example 3-12 Parameter Passing Using WITH and RETURNING 

  do_a_heading with option 45, title 'Big test', 
                  returning status s 
  print 'Status was: '; s 
  stop
  routine do_a_heading with title, option, returning status 
    print '** '; title; ' **... option:'; option 
    status = -1 
  end routine

PURPOSE:

The purpose of the optional parameters is to pass data in and out of routines.

DESCRIPTION:

The parameter NAMES are used to pass data into and out of a routine. You can have up to 16 INPUT (with) and 16 OUTPUT (returning) parameters (32 total).

Currently the RETURNING parameters must all be non-array elements.

3.5.2 Private Variables in Routines

FORMAT:


    ROUTINE routine_name: PRIVATE var, var, var, ... 
or 
    ROUTINE routine_name: PRIVATE INTEGER var, STRING var, STRING var, ...

EXAMPLE:

Example 3-13 Private variables in routines 

  do_totals 
  end
 
  routine do_totals: private mytotal, desc$ 
    mytotal = 15 
    desc$ = 'Test Totals' 
    print desc$; mytotal 
  end routine
 
 
Test Totals 15

DESCRIPTION

SheerPower allows you to use private variables in a routine. Private variables are variables identified with a specific routine. This option allows you to use the same variable names more than once because, internally, SheerPower prefixes the variables with the routine name and a "$" character.

In the above example, the private variables "mytotal" and "desc$" are internally known to SheerPower as:

do_totals$mytotal

do_totals$desc$

From inside the routine, you can reference the variables by their private names. For example: mytotal, desc$

From outside the routine (or while debugging the code), you can reference the private variables by their internal known names. For example: do_totals$mytotal, do_totals$desc$

Note
See Appendix M, SheerPower and Program Segmentation for more on routines and private routines in SheerPower.

Previous Next Contents Index