FORMAT:

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

EXAMPLE:

Example 3-14 Passing parameters with private variables

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, private tlen tlen = len(title) print '** '; title; ' **... option:'; option; ', len: '; tlen status = -1 end routine ** Big test **... option: 45 , len: 8 Status was: -1

3.5.4 Error Messages when Passing Routine Parameters

If you try to access a parameter incorrectly an error message will result:

Example 3-15 Error messages when passing routine parameters

do_totals with tttitle "my title" stop routine do_totals with title print title end routine

The above example would generate TWO errors:

Possible coding error - variables used, but not assigned: DO_TOTALS$TITLE (no data value got into the TITLE parameter) Inconsistant ROUTINE parameter passing: Routine DO_TOTALS, Parameter TTTITLE (This isn't the right spelling of the TITLE parameter)

Each program unit is made up of program lines. A program line consists of one or more statements.

When SheerPower executes a program, it starts at the first line and executes all the statements in that program line. Then it goes to the next line and executes all the statements in that line and so on.

Multiple statements can be placed on a single line, delimited by the \ (backslash). CHR$(10) also signals the same as a \. A \ terminating the line implies an "&".

Example 3-16 Multiple statements on a single line

for z1 = 4. to 7. step .5 \ print z1 \ next z1 end run 4 4.5 5 5.5 6 6.5 7

3.6.1 Continuing Program Lines and Implied Continuation

You can continue a statement on the next physical line by using an ampersand (&). This allows you to continue a statement that is too long to fit on one line.

To continue a statement, place the ampersand at the end of the continued line. You can also place an optional ampersand at the beginning of the next line. For example:

Example 3-17 Continuing program lines using the AMPERSAND (&)

input 'Please enter your name': name$ print 'Hello, '; name$ print 'Today is '; day$ print name$; & ', have a good '; & // required ampersand & day$ // optional ampersand end Please enter your name? Julian Hello, Julian Today is Tuesday Julian, have a good Tuesday

You can continue statements between words; however, you cannot break up a word.

An ampersand (&) may be used to identify a statement that is continued on the next physical line. The ampersand is acceptable, but is no longer required in some cases. Implied continuation has been implemented for:

• comma (,) list items
• all operators having two arguments; i.e. trailing "+", "AND", "OR", "*", "/", etc., implies that the rest of the code is on the following line

Example 3-18 Comma-separated list continuation

open structure cust: name 'sptools:customer', // no ampersand access outin, // no ampersand lock close structure cust end

Example 3-19 Implied continuation with '+', 'AND'

print 'Today is the first day of the ' + // no ampersand 'rest of your life.' a$ = 'walk' b$ = 'walk' c$ = 'walk' if a$ = b$ and // no ampersand a$ = c$ then print 'All are the same.' end if end Today is the first day of the rest of your life. All are the same.

3.7 Comments

Inserting COMMENTS in programs will allow the code to be easily understood in the future. Comments are not executable statements. They are simply included in source code for informational purposes. They are seen when a program is listed or printed out. However, SheerPower will ignore them when it executes a program.

There are two types of comments allowed in SheerPower: exclamation point (!) and double-forward slash (//). The exclamation point commenting is used for creating the program and routine headers. The double-forward slash commenting is used for inserting comments within routines.

Example 3-20 Comments in programs - (//)

dim name$(10) // setup array rem main logic for i = 1 to 10 // Begin the loop input 'Please enter your name': name$(i) // ask for a name if _exit then exit for // end if they want print 'Hello, '; name$(i) // print hello next i // end the loop end Please enter your name? Mary Hello, Mary Please enter your name? exit <---- type in 'exit'

3.7.1 (//) comment_text

FORMAT:

// comment_text

EXAMPLE:

Example 3-21 Comment text

input 'Please enter your name': name$ // ask for a name print 'Hello, '; name$ // say hello end Please enter your name? Mike Hello, Mike

PURPOSE:

All programs should be commented. Comments teach future programmers, as well as yourself, how a program works. The proper use of comments can dramatically enhance the ability to maintain a program.

Comments are used to put headers in routines, and to comment code within routines. Always document code thoroughly in each routine header. Ideally, commenting should rarely be done inside the actual routine. If the routine is written simply and kept short, then no comments are needed within the code. Keep the size and scope of the routine limited and obvious for future reference.

DESCRIPTION:

Comments can be used to clarify parts of your program as shown in the example above.

When the program is listed or printed, the commented line is displayed as it was written in the source code.

When SheerPower executes the above program, it executes the INPUT statement, ignores the "//" and the comment text following it, and continues execution at the PRINT statement. The "//" does not have to be placed at the beginning of a physical line. It can be used anywhere on a program line.

3.7.2 Routine Headers

In the SheerPower Rapid Development Environment, the GOLD/p keystroke will automatically create the program header template. The GOLD/r keystroke will automatically create the routine header template. The 'GOLD' keys in SPDEV are the [Esc] (Escape) key or the [NumLock] (Numbers Lock) key. For more special keystrokes in SPDEV, refer to Appendix F, Keystrokes for SheerPower Rapid Development Environment.

Below is an example of a Routine Header:

Example 3-22 Routine header sample

!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! f i n d _ p e a k _ c a m s _ a n d _ v i e w e r s !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ! ! Brief description: ! This routine finds the peak number of cams logged in and peak ! number of live viewers watching each day. ! ! Expected on entry: ! total_live_viewers = number of live viewers ! live_cameras = number of live cams ! ! Locals used: ! ! ! ! Results on exit: ! peak_viewers = peak number of live viewers ! peak_cameras = peak number of live cameras ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%