NOTICE

Touch Technologies, Inc. (TTI) has prepared this publication for use by TTI personnel, licensees, and customers. This information is protected by copyright. No part of this document may be photocopied, reproduced or translated to another language without prior written consent of Touch Technologies, Incorporated.

TTI believes the information described in this publication is accurate and reliable; much care has been taken in its preparation. However, no responsibility, financial or otherwise, is accepted for any consequences arising out of the use of this material.

The information contained herein is subject to change without notice and should not be construed as a commitment by Touch Technologies, Inc.

Revised: October 29, 2009 for V5.0

Copyright ©2001-2009 Touch Technologies, Inc.

Contents

Index

SheerPower 4GL is a next generation database language for Windows. It works on Windows 2000, Windows NT, Windows XP, Windows Vista, and Windows Server. It includes a Rapid Development Environment (SPDEV) and a fourth-generation Database Language (SP4GL) .

The SheerPower language:

• is concise and powerful
• promotes structured programming
• is easy to use--even for programming novices

SheerPower excels at both character and mathematical utility, combining them into a powerful, easy-to-use framework. SheerPower can be used to write programs of any size, from simple-input applications to vast database infrastructures and Web applications. SheerPower's layout may look somewhat similar to that of a structured BASIC program, but SheerPower is beyond BASIC!

SheerPower includes a transparent interface to the ARS (Advanced Record System) database engine as well as to other database engines. (ARS is bundled into SheerPower).

ARS is integrated into SheerPower featuring extremely high speed sequential and random access to database information. In addition, ARS is optimized for client/server applications through the use of high performance memory resident shared data.

The interface includes:

• simple structure statements for complex data manipulations
• numerous extensions which allow the technical programmer to develop advanced applications

The SheerPower environment is designed for developing complex applications rapidly. This interactive environment:

• allows immediate response and fast development
• allows you to interrupt program execution, change code and then continue execution
• has high-level debugging facilities for pinpointing program bugs quickly and accurately
• returns errors immediately--for rapid development--while code is optimized by the compiler

Development cycle time is the time it takes to edit, compile, link, run and debug code. SheerPower reduces this time by providing an interactive and fast response environment. SheerPower offers features that cut cycle time significantly--up to 80%.

You will find SheerPower an exciting and powerful programming tool.

SheerPower Reference Manuals

All SheerPower manuals are designed to provide information in a manner that is concise and easy to use. The manuals are:

• A Guide to the SheerPower 4GL Language
• SheerPower Coding Standards

Purpose of this Guide

The purpose of this Guide is to present the information you will need to develop programs with SheerPower. The intent is to provide you, the user, with simple and concise explanations of the SheerPower system, features, and language. This manual is designed to provide a basic and thorough explanation of each element. This manual can also be used as a reference guide by advanced users.

Intended Audience

This Guide is written for both experienced programmers and those self-learners who have had some exposure to computers and programming languages.

User Feedback and Technical Support

We want your feedback! Tell us what YOU think about:

• SheerPower 4GL
• the SheerPower 4GL WEBSITE
• the SheerPower 4GL MANUAL

We really want to know!

If you have any technical issues, please email them to us and we will respond!!

Send all feedback and technical support emails to:

[email protected]

Thank you for using SheerPower 4GL!

Download SheerPower 4GL

Download the latest version of SheerPower 4GL by clicking HERE .

Click on the FREE!! Download SheerPower 4GL NOW! link.

Follow the instructions on the download webpage to download and install SheerPower 4GL.

How to Start SheerPower Rapid Development Environment

To start SheerPower Rapid Development Environment (SPDEV), double click the SheerPower shortcut icon located on your desktop---a circle with a lightning bolt through it.

Below is an image of what SheerPower Rapid Development Environment looks like when it is running.

To create a new program in SheerPower Rapid Development Environment, click once on the New icon in the toolbar---a white paper with one corner folded. This will create a new file for you to work in.

You can also click on File in the SPDEV toolbar and select New from the drop down menu of choices to create a new file.

The Name New File... dialog box will appear and ask you to name your new file, and to specify the location you want to save it to.

Type the name of the new program file inside the File name: field. Name this new file Menu.

The default file type to save a file is .SPSRC. This is a SheerPower source program file. When you click on [Save] the file type extension will automatically be added on to the file name. Clicking on the down arrow will drop down a list of different file types to save your files as.

Since .SPSRC is already selected as the file type, click on [Save].

After you click on the [Save] button in the "Name New File..." dialog box, a new document window will open within SheerPower Rapid Development Environment.

A dialog box will also appear prompting you for your name, company name and program name.

When you fill in this information and click on [OK], a program template will automatically be inserted into your new program file. See Appendix I, Developing Professional Applications with SheerPower for a detailed discussion on the special features built-in to SheerPower designed to save time and money when creating professional applications.

For the purpose of this basic tutorial, click on [Cancel].

You can now begin to write your new SheerPower program inside the new document window.

Copy and paste or type the following program into the new menu.spsrc file inside SPDEV.

Note The examples show how commands or statements are used. Wherever possible, the example is a full program rather than a program fragment. You are encouraged to type in (or copy/paste) the SheerPower examples into SPDEV throughout this manual and try running them.

Example 1-1 Menu Program

do line input menu '"calculator" = calc,"DOS prompt" = dos,"exit"': ans$ if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop end

RUN this program by clicking on the Run icon in the SPDEV toolbar---the running man.

The following menu will appear:

Click on the word calculator in the menu. The program will run your Windows calculator program.

Click on DOS prompt in the menu. The program will run the MS DOS Prompt (or Command Prompt) program.

Click on exit or the [X] to close the menu. The console window will appear. Close it by typing in exit and pressing [Enter], or by clicking on the [X] in the top right corner of the window.

To SAVE your program in SheerPower Rapid Development Environment, click once on the Save icon in the SPDEV toolbar---the floppy disk icon.

You can also click on File in the SPDEV toolbar and select Save from the drop down menu.

If you have multiple files open in SheerPower Rapid Development Environment that you wish to save, click on the Save All icon in the SPDEV toolbar---the icon with three floppy discs together.

Each time you RUN a program file from SPDEV, SheerPower automatically SAVES it.

1.2.3 File Backup Versions

SPDEV has a built-in file backup feature that allows you to keep up to the last 10 versions of any file edited in SPDEV. Each time you save your file in SPDEV, the old version is saved with a version number behind it:

myprogram.spsrc <-- current version myprogram.spsrc-1 <-- last saved version myprogram.spsrc-2 <-- 2nd last saved version myprogram.spsrc-3 <-- 3rd last saved version

To choose the number of backup file versions for SPDEV to automatically save, click on Options in the SPDEV toolbar. Select Change System Settings, then enter in the Number of Backup File Versions to save (0-10).

To delete any unwanted SPDEV backup files, click on the Purge icon in the SPDEV toolbar. The Purge Versions dialog box will appear.

Select the folder or files that you wish to purge in the Look in: field. You can choose to purge either SheerPower (.spsrc) files or all file types in the drop down list at the bottom of the dialog box.

A Purge Subfolders option is also available inside the Purge Versions dialogbox. Just place a check inside the checkbox if you want to purge backup files that are inside the subfolders of the directory you have selected.

Once you have selected the folder or files to purge, and the file type, click on the Purge Now button. You will be prompted to confirm that you want to purge the files in the selected path. Click on the OK button. The Purge Results window will appear containing a list of all the backup files purged. If no backup files were in the folder nothing will be purged.

The option to purge only the backup versions of the current file you are working in is also available. Click on File in the toolbar options, then select Purge Current File.

Note Keep Your Valuable Source Code Hidden From Prying Eyes! Optional SheerPower 4GL GOLD Licenses are available. Royalty FREE distribution---you can always distribute SheerPower-based applications to others---royalty free! And, you can do so without the optional SheerPower 4GL License, but you must provide them with the source code to your application. Visit our website for more information.

In the SPDEV toolbar, click on the DEPLOY icon.

This will bring up the Enter License Key dialog box. You can copy and paste your SheerPower 4GL license key information in here. Click on [OK] to proceed with the deployment of the program.

Note You will see the Enter License Key dialog box the FIRST TIME you do a DEPLOY when newly running SPDEV. If you restarted SPDEV 5 times in a day, you would see the "Enter License Key" dialog box appear 5 times (providing you deployed each time).

The Deployment Properties dialog box will appear. You can now enter a Password to protect this program file.

This is an OPTIONAL PASSWORD used to PROTECT your program. This way, only someone who knows the passwordcan run the program.

So, you could post your .SPRUN file on the Internet---and anyone could download it. But, only those who have the PASSWORD could run it!!

Place a check in the box beside Don't show this dialog again if you do not want to be prompted to enter a password every time you click on the deploy icon.

Note If you want to deploy a program with a password, you have to specify a password each time you deploy.

Click on the [OK] button to deploy the program.

You will now see in the bottom frame of the SPDEV window that deploying the program compiled it. You will also see the number of lines of code, file size, and whether or not it was a clean build or if there were any compile errors.

Look inside your SheerPower folder (c:\sheerpower is the default location). You will see that a file named menu.sprun has been created.

This .SPRUN file allows you to distribute applications without the recipients ever being able to see the source code.

Optional SheerPower 4GL Licenses Available

Royalty FREE distribution---you can always distribute SheerPower-based applications to others---royalty free! And, you can do so without the optional SheerPower 4GL Licenses, but you must provide them with the source code to your application.

Once you have written a program you can DEPLOY it by clicking on the Deploy icon in the toolbar.

Deploying your main source code before you run your program will tell you immediately if there are any compile errors in your code. Any errors will appear inside the bottom window frame of SheerPower Rapid Development Environment. If there are no compile errors, SheerPower will tell you that you have a clean build. The name of your file, the number of lines written, the speed it was compiled at, and the size of the file will also appear inside the SheerPower Rapid Development Environment bottom window frame.

Build of C:\SheerPower\test.spsrc Lines compiled: 58 (24800/min), code: 1KB Clean build for C:\SheerPower\test.sprun

The DEPLOY feature also creates a .SPRUN file---such as test.sprun. SPRUN files are useful in that:

• All source code is hidden---preserving your intellectual property.
• A password can be attached to the program---only those that know the password can run the program.
• SPRUN files are textual---so they can easily be emailed or made available on a web site.

Deployed applications can include the %COMPILE directive. The %COMPILE directive allows you to enter in up to 100 lines of text inside the .SPRUN file. This text cannot be altered or the application will not run. See Section 3.9.1,%COMPILE for details.

At any time you can RUN your main source program. To run a program in SheerPower Rapid Development Environment, click on the Run icon in the toolbar---the running man.

You can also Run a SheerPower program by double-clicking on its name using Windows Explorer. Both SPSRC and SPRUN program files can be run in this way. You can also DRAG-and-DROP either SPSRC or SPRUN program files onto the DESKTOP---then double-click to run the program.

How to Run a SheerPower Program on Another Computer

To run a SheerPower program on another computer:

• Download and install the SheerPower 4GL Virtual Machine to the other computer.
• Double-click on either the .SPSRC or .SPRUN file to run the program.

In the program examples, keywords in SheerPower statements and commands are in bold, and information you (the user) supply is in regular text. The program examples are designed so that they can be typed, or copied and pasted into the SheerPower Rapid Development Environment and run. Below each example, the results are shown.

Try the following examples:

Example 1-2 Menu Program

do line input menu '"calculator" = calc,"DOS prompt" = dos,"exit"': ans$ if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop end

Example 1-3 Quiz Program Example

// A simple quiz program woodpecker$ = 'sheerpower:samples\woodpecker.jpg' quiz_form$ = '<sheerpower persist><title>Quiz</title><form>' + '<center><h3>Skill Testing Question</center></h3>' + '<img src="' + woodpecker$ + '" border=3 align=middle>' quiz_form$ = quiz_form$ + '<font color=green> ' + '<b>What type of woodpecker' + ' is in this photograph?</b></font><p>' quiz_form$ = quiz_form$ + '<input type=radio name=birdname ' + 'value="Pileated Woodpecker"> ' + '<i>Pileated Woodpecker<p>' quiz_form$ = quiz_form$ + '<input type=radio name=birdname ' + 'value="Hairy Woodpecker"> Hairy Woodpecker<p>' quiz_form$ = quiz_form$ + '<input type=radio name=birdname ' + 'value="Redheaded Woodpecker"> ' + 'Redheaded Woodpecker</i></b>' quiz_form$ = quiz_form$ + '<p><input type=submit name=submit value="Submit">' + '<input type=submit name=exit>' + '</form>' correct$ = 'Hairy Woodpecker' good$ = '<sheerpower width=500 height=300 color=green>' + '<form><h1>Congratulations!! ' + correct$ + ' is the correct answer!!</h1>' + '<p><center><input type=submit></center></form>' do line input dialogbox quiz_form$: ans$ if _exit then stop z0$ = element$(ans$, 1, chr$(26)) // get the first response value$ = element$(z0$, 2, '=') // get the the value (name=value) if value$ = correct$ then exit do message error: "Sorry, this is not a ";value$ loop line input dialogbox good$: ans$ end

Example 1-4 NEWS Headline Program Example

// To present the top news story from CNN.COM // Note: From time to time CNN changes its format, so the // main$ and end_main$ sometimes have to be changed. main$ = '<div class="CNN_homeBox">' end_main$ = '</div>' begin_form$ = '<form>' + '<h1><font color=green>' + 'Top News from CNN' + '</font></h1>' + '<br><h2>' news_ch = _channel open #news_ch: name 'http://www.cnn.com' crlf$=chr$(13)+chr$(10) state$ = 'find_main' do line input #news_ch, eof eof?: text$ if eof? then exit do select case state$ case 'find_main' z0 = pos(text$, main$) if z0 = 0 then repeat do z0$ = mid(text$, z0+len(main$)) z0 = pos(z0$, '>') if z0 = 0 then repeat do z0$ = mid(z0$, z0+1) dbox$ = begin_form$ +z0$ state$ = 'gather_news' case 'gather_news' z0 = pos(text$, end_main$) if z0 > 0 then dbox$ = dbox$ + left(text$, z0-1) state$ = 'show_news' repeat do end if dbox$ = dbox$ + text$ + crlf$ repeat do case 'show_news' // first add in the http://www.cnn.com to any anchors dbox$ = replace$(dbox$, '<a href="==<a href="http://www.cnn.com/',',', '==') // now finish off the input form with a single "submit" button dbox$ = dbox$ + '</h2><p><input type=submit></form>' line input dialogbox dbox$: ans$ exit do end select loop end

Example 1-5 Expression Evaluator Program Example

// Evaluate an expression // Type in the expression and press [enter] // // The expression can by very complex. For example: // ((34-324)/14)*10.1234 declare dynamic answer formtop$= '<sheerpower persist>' + '<title>Expression Evaluator</title>' + '<form><h2>Enter an expression</h2>' + 'For example--> ((344574647-324978)/154574)*13350.1234' + '<input name=expr submit>' + '<p>' formend$ = '<p><input type=submit name=submit value="Submit">' + '<input type=submit name=exit value="Exit"></form>' form$ = formtop$ + formend$ do input dialogbox form$: response$ if _exit then exit do z0$ = element$(response$, 1, chr$(26)) // get the first field expr$ = element$(z0$, 2, '=') // get the data for the first field if expr$ = '' then repeat do when exception in answer = eval(expr$) use answer = extext$ end when if dtype(answer) <> 1 then answer = str$(answer) form$ = formtop$ + '<h2><font color=green>' + expr$ + '</font></h2>' + '<h3>' + answer + '</h3>' + formend$ loop end

1.5 Developing Professional Applications with SheerPower

SheerPower Rapid Development Environment makes professional application development easy with BUILT-IN TEMPLATES, and SPECIAL KEYSTROKES.

Some of SheerPower's features are:

• Program Template
• Routine Header Template
• Auto-organize routines
• Auto-align "=" within routines and headers
• Easy commenting/uncommenting code
• Generate special DEBUG comment lines--easy to find!

Plus many more special keystrokes that enable a programmer to quickly and efficiently write clean, readable and accurate code.

See Appendix I, Developing Professional Applications with SheerPower for a detailed discussion on the special features built-in to SheerPower designed to save time and money when creating professional applications.

See Appendix F, Keystrokes for SheerPower Rapid Development Environment for a complete reference guide to the special keystrokes in SheerPower Rapid Development Environment.

If you need to open an existing file stored on your computer to read or edit in SPDEV, click on the Open icon in the toolbar---an open file folder. You can then choose the directory and file you want to open from the OPEN dialog box that appears.

You can also open an existing file by clicking on File in the SPDEV toolbar, then selecting Open from the drop down menu. The Open dialog box will appear:

Whether you are creating a new file or opening an existing file to edit in SheerPower Rapid Development Environment, the default folder location is c:\sheerpower. The default file type being created/searched for is any of the SheerPower program files (*.spsrc, *.int, *.spinc and *.inc).

To open a different file type, click on the down arrow beside the Files of type: field (located at the bottom of the dialog box). Choose All Files to see all of files of the specified type within that folder.

To search for a file or to save your file to a different folder (other than c:\sheerpower), click on the down arrow beside the Look in: field (located at the top of the dialog box) and choose the folder you wish to search/save in.

SPDEV can open ANY kind of file that is not binary data.

If you make an error in your program, such as misspelling the word print:

Example 1-6 SheerPower program error message

input 'Please enter your name' : name$ printt 'Hello, '; name$ Build of C:\SheerPower\tests.spsrc file: C:\SheerPower\tests.spsrc (line 2, column 0): Unrecognized statement

SheerPower will display an error message in the bottom frame of the window (the results window). You can double click on the line number given in the error message. SheerPower will highlight the line of code containing the error for you, and place the cursor at the beginning of the error. You can now retype the correction and rebuild your main source program.

1.9 SP4GL Console Window

When a main source program is run in SheerPower Rapid Development Environment, the SP4GL Console Window will open (also referred to as "console window").

To open the SP4GL Console Window without running a main source program, click on the SP4GL Console Window icon in the SPDEV toolbar---the square with a lightning bolt through it.

To close the SP4GL Console Window, type in exit and press the [Enter] key, or click the X in the top right corner of the window.

SP4GL Console Window The console window must be closed before attempting to run a program again. The running man icon in the SheerPower Rapid Development Environment (SPDEV) toolbar will remain greyed out until the console window is closed. More than one instance of the SP4GL Console Window can be opened by clicking on the SP4GL Console Window icon in the SPDEV toolbar.

1.9.1 SP4GL Console Window Keystrokes

In the console window the mouse can be used to select (highlight) text on the screen.

Below is a table containing the special keystrokes available when working in the SP4GL Console Window.

Table 1-1 SP4GL Console Window

Keystroke	Function Performed
ctrl/a	selects all text (both on and off screen)
ctrl/c	places selected text into the clipboard
ctrl/m	places contents of message history into the clipboard
ctrl/t	places contents of screen (including scroll buffers) into the clipboard

In SPDEV, you can get help by clicking on the Help icon in the toolbar---a question mark.

You can get help when in the console window by typing help and pressing the [Enter] key or by clicking on the ? icon in the toolbar.

Selecting HELP in SPDEV or the console window will open up a new browser window that loads the online SheerPower documentation.

Utilize the Contents or the Index to help you find the required documentation.

User Conventions

In some places in this manual, the format of statements and commands is represented abstractly. For example:

Format: [LET] var = expr

Certain conventions are used to represent values which you (the user) must supply. These conventions are always shown in lowercase. These are the user conventions:

Symbol	Description
array	Array element.
block of code	A SheerPower statement or a series of SheerPower statements.
chnl	An I/O channel associated with a file.
chnl_num	An I/O channel associated with a file.
cond_expr	Conditional expression.
col	Column. Used in the TAB or AT option to indicate the column to print at.
const	Constant value.
expr	Expression. May be a variable, constant, array element, structure reference, etc. or any combination of the previous, separated by operators.
field_expr	Field name expression.
func	Function.
handl	Exception handler. Pertaining to an exception handling routine.
handler	The block of code in an exception handler which is executed when an exception is generated.
int	Integer value.
int_expr	Integer expression.
int_var	Integer variable.
label	Alphanumeric statement label.
libr	Pertaining to libraries.
line_num	Program line number.
name	Name. Indicates the declaration of a name or the name of a program unit, such as a subprogram.
num	Numeric value. Num indicates that either a real or integer numeric value may be used.
num_expr	Numeric expression. Num_expr indicates that either a real or integer numeric value may be used.
num_var	Numeric variable.
param	An expression which is passed to a function, subprogram or other program unit. A parameter can be any valid SheerPower expression.
protected block	The block of code protected by an exception handling routine.
real	Real number. Indicates that only a real number may be used.
row	Row. Used in the AT option to specify the row to print at.
str	String. Str indicates that only a string value may be used.
str_expr	String expression.
str_var	String variable.
struc	A SheerPower structure.
struc_name	Structure name.
struc_expr	Structure expression.
sub	A SheerPower subprogram.
target	The target point of a branch statement. The target can be either a program line number, an alphanumeric label, or a ROUTINE statement.
uncond_expr	Unconditional expression. Uncond_expr indicates that only an unconditional expression can be used.
var	Variable. May be a simple variable, array element or a structure reference.

Other Conventions

Other conventions used in this manual are:

[ ]	Optional portions of a statement are enclosed in brackets: INPUT [PROMPT str_expr] : var
{ | }	Braces combined with a vertical bar indicate that one of the elements in the braces must be chosen. The elements are separated by the vertical bar: EXIT {FOR | DO}
[ | ]	Brackets combined with a vertical bar indicates that one of the options in the brackets can be used. The elements are separated by the vertical bar. Only one of the elements can be used: DO [WHILE expr | UNTIL expr]
...	An ellipsis indicates that the language element can be repeated. An ellipsis following an option enclosed in brackets indicates that you can repeat the format of the whole option. INPUT [PROMPT str_expr] : var, var...
dashes	Three sets of dashes indicate a block of code. DO --- --- block of code --- LOOP
. . .	A vertical ellipsis indicates the continuation of a body of program code which is not a defined block of code.

1.12 Presentation of Command and Statement Information

Part of this chapter and several other chapters in this Guide describe the commands and statements in the SheerPower language. The purpose of this section is to explain how the command and statement information is presented.

Statements that can only be used in connection with one another, such as if then or the select case statements, are described together. Each command and statement description includes the following information:

FORMAT:

input [options] var [, var...]

FORMAT:

extract structure struc_name: key field = expr1 [to expr2] --- --- block of code --- end extract

The FORMAT contains the command or statement format. This includes the required keywords and the optional elements, if there are any.

Keywords are words that must be typed exactly as shown in the format. Keywords inside the program examples are shown in bold; e.g., extract structure, key, to, end extract. The elements in regular text represent information that must be provided by the user in order to use the statement. For example, "struc_name" (the structure name) must be provided by the user in this statement. "field" and "expr1" information must also be provided.

Keywords and elements in brackets are optional. Multiple options are separated with commas.

SheerPower is space sensitive, so spaces must be included where they are shown in the format. Either the single quote or double quote can be used as long as they are paired.

EXAMPLE:

Example 1-7 Presentation of command and statement information

input 'Enter full name', timeout 30, elapsed x: name$ print name$ print 'Elapsed time: '; x end Enter full name? TTI Tester <---- type in your name here, then press the [Enter] key TTI Tester Elapsed time: 13

The EXAMPLE shows how the command or statement is used. Wherever possible, the example is a full program rather than a program fragment.

You are encouraged to type in (or copy/paste) the SheerPower examples into SPDEV throughout this manual and try running them.

PURPOSE:

In some cases, PURPOSE information is provided for usage clarity.

DESCRIPTION:

The DESCRIPTION tells about the command or statement, explains how it works, and other specific information.

Chapter 6, Built-in Functions of this Guide provides information on SheerPower's built-in functions, error and exception messages, and other general topics. You will want to get familiar with the built-in functions, as they will allow you to easily manipulate data.

Now that you have an idea of how to use this manual and work in SheerPower, the remainder of this Guide will provide the information you need to create and use SheerPower programs.

This chapter describes SheerPower debug facilities and how to use them. It also describes the commands that can be used in the SP4GL Console Window for debugging and experimentation purposes.

To open the SP4GL Console Window, click once on the SP4GL Console Window icon inside SheerPower Rapid Development Environment (SPDEV) in the top toolbar---the square with a lightning bolt through it.

Using the SP4GL Console Window

While writing a program in SPDEV, the SP4GL CONSOLE WINDOW (also referred to as the "console window") is utilized for debugging and experimentation purposes.

Note When using the scrollbars on the console window, the maximum number of scrollback lines is 500.

SheerPower COMMANDS cause SheerPower to take some action immediately. SheerPower commands are not normally used inside programs. Here is a list of SheerPower commands that are generally used only in the console window:

• BUILD
• RUN
• LIST
• GO
• STEP
• SHOW FILES

SheerPower STATEMENTS are used inside program files (.SPSRC files inside SPDEV).

When a SheerPower statement is used inside the console window, it becomes a COMMAND. For example, the PRINT statement becomes a command when used in the console window. All SheerPower statements are available to be used as commands while debugging inside the console window.

The SP4GL Console Window is a limited editing environment. One or more commands can be performed at a time. Multiple commands must be separated by a backslash. If the line ends with a backslash, additional commands can be entered on the next line. The following example shows a single PRINT command inside the console window.

To perform the following example, open the SP4GL Console Window by clicking on the SP4GL Console Window icon in the SPDEV toolbar. Inside the console window, type:

print 'Hi there!'

and press the [Enter] key.

Example 2-1 Print command in the SP4GL Console Window

print 'Hi there!' //<--- your entry Hi there! <--- result

Type the example below into the console window:

Example 2-2 Entering multiple commands in the SP4GL Console Window

for i = 1 to 10\ print i\ next i 1 //<--result 2 3 4 5 6 7 8 9 10 OR: for i = 1 to 10\print i\next i 1 //<--result 2 3 4 5 6 7 8 9 10

Here is another example you can try typing inside the console window. Note that the date$ function will return the current date. This will be different than the date you see returned in this example.

Example 2-3 Print command in the SP4GL Console Window

date$ //<--press [Enter] 20010710 //<--result

2.1.1 Recalling Previous Commands in SheerPower

The SP4GL Console Window handles command recall. The user can recall the last 100 previously entered commands by using the UP and DOWN arrow keys.

To perform the following example, open the console window by clicking on the SP4GL Console Window icon in the SPDEV toolbar. Inside the console window, type:

Example 2-4 Command recall in the SP4GL Console Window

print date$ <--- type this line in and press [Enter] 20010716 //<--result print date$(days(date$), 3) <--- type this line in and press [Enter] 16-JUL-2001 //<--result print date$(days(date$), 3) <--- press the UP arrow key print date$ <--- press the UP arrow key, then press [Enter] 20010716 //<--result

2.1.2 Using the [Tab] Key Features

When in the console window, the [Tab] key can be used to perform various operations that cut down the time it takes to debug program code. As you get familiar with SheerPower and the SheerPower language, you will find that the [Tab] key features can be very helpful.

In the SP4GL Console Window, enter part of a command and then press the [Tab] key. SheerPower will then supply the full name of the command. If the command is ambiguous, a selection menu of all valid choices will appear.

In the following example, SheerPower completes "so" to form the command "sort".

Open the SP4GL Console Window by clicking on the SP4GL Console Window icon in the SPDEV toolbar. At the flashing cursor in the console window, type in the word "so". Press the [Tab] key and you will see "so" completed to be the command "sort".

Example 2-5 Command completion

so[Tab] <--- your entry, press [Tab] sort <--- SheerPower supplies

Next, type the word "in", then press the [Tab] key. In this example, "in" is ambiguous, so SheerPower provides a menu of choices:

Example 2-6 Command completion

in[Tab] +--Choices---+ | include | | inf | | input | +------------+

The [Tab] key can be used to correct misspelled commands in the console window, as well as misspelled statements in SPDEV. Just position the cursor on the misspelled word and press the [Tab] key. The word will be replaced with its correct spelling. In the example below, the misspelled command SET STRCTRE is changed instantly to the correct command spelling when the [Tab] key is pressed.

To perform the following example, open the SP4GL Console Window by clicking on the SP4GL Console Window icon in the SPDEV toolbar. Inside the console window, type:

Example 2-7 Spelling correction

set strctre[Tab] //<-- press [Tab] set structure

2.1.2.3 Expanding Abbreviations

SheerPower uses abbreviations for a number of commands. The [Tab] key can be used with any of the specific abbreviations to expand the abbreviations. To use this feature, enter an abbreviation and then press the [Tab] key. The period '.' must be used after each abbreviation. The current abbreviations that can be used are:

os.	open structure
es.	extract structure
ee.	end extract
in.	include
ex.	exclude
fe.	for each
e.	edit
l.	list
p.	print
pu.	print using
ss.	set structure
pa.	print at
li.	line input
pc.	print #
oc.	open #
pe.	print _extracted
lm.	line input menu
ls.	line input screen

Open a new file inside SheerPower Rapid Development Environment by clicking once on the New icon in the toolbar---a white paper with one corner folded.

Name the new file "sample_program". Press the Save button inside the New File dialog box. The file type .SPSRC will automatically be added when the Save button is pressed.

The Get Program Info dialogbox will appear, prompting you for your name, company name and program name. This will create a Program Template inside the new program file. For the purpose of this documentation, press the [Cancel] button. This will create an empty program file, with no program template.

See Section I.2, Program Template for more on creating a program template within a .SPSRC file. If you do create a program template in your new file, copy and paste or type the following program into the new file below the Main Logic Area above the word stop.

Otherwise, copy and paste or type the following program into the new program file:

Example 2-8 Program example

do line input menu '"Calculator" = calc,"DOS Prompt" = dos,"EXIT"': ans$ if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop

You can run this program by clicking once on the Run icon---the running man. The result of the program is shown below:

Choose 'EXIT' in the menu to complete running the program, then close the console window by typing 'exit' or clicking on the 'X' in the top right corner of the window.

This example will be used throughout the next few sections of this chapter.

Notice that after you completed running the sample program the following information appears in the results window (at the bottom of SPDEV) inside the Build tab:

Build of c:\sheerpower\samples\sample_program.spsrc Lines processed: 10 (30000/min), code space used: 1KB Clean build for c:\sheerpower\samples\sample_program.spsrc

If you had any compile errors in your source code, they will be listed here along with the location of the error, and the type of error. You can click directly on the line detailing the error and it will highlight the line of code containing the error directly in the program.

debug on for i = 1 to 6 prnt i // typo error in the print statement if i = 4 then halt next i end

When you run the program, the following information is displayed in the Build tab window at the bottom of SPDEV:

Build of c:\sheerpower\samples\test.spsrc file: c:\sheerpower\samples\test.spsrc (line 3, column 1): Unrecognized statement Unrecognized statement at MAIN.0002

Left click directly on (line 3, column 1): Unrecognized statement. It will highlight that text in blue, and inside your program the line of code with the error will be highlighted in yellow. You can then correct the typo in the statement and rebuild the program.

In the console window, errors are returned either immediately after typing a syntactically incorrect line, or when the RUN command is given and your program is syntactically incorrect.

Errors happen when the program is compiling. Exceptions happen as the program is running.

In the case that the error happens outside of a routine (in the main logic area) the location of the error will always start with "main" followed by a period. Following the period is the source code line number.

I.E., main.0006 means the error occurred in the 6th line from the top of the file.

I.E., do_totals.0003 means the error occurred in 3 lines from the definition of the routine called do_totals.

For a list of the different SheerPower error and exception messages, see Appendix C, SheerPower's Error and Exception Messages.

In SPDEV the Alt + UP or DOWN arrow key can be used to move up or down a specific number of lines in your file. For more specialized programming keystrokes in SPDEV, see Appendix F, Keystrokes for SheerPower Rapid Development Environment.

2.4.1 BUILD

FORMAT:

[BUILD 'program_name']

EXAMPLE:

To run this example, open the console window by clicking once on the SP4GL Console Window icon in the SPDEV toolbar. Type in the example as shown below inside the SP4GL Console Window, then press [Enter].

Example 2-9 BUILD command in SP4GL Console Window

build 'sample_program' //<--- type this line in and press [Enter] Building c:\sheerpower\sample_program.spsrc ... Lines compiled: 11 (33000/min), code: 1KB

PURPOSE:

Use the BUILD command to build a program in the SP4GL Console Window. Any build errors will be listed when you perform the BUILD command.

DESCRIPTION:

The BUILD command used in the console window defaults to the SheerPower folder. When building a program that is not stored inside the SheerPower folder, the path (location) of the program must be specified. See the following example:

Example 2-10 BUILD command in SP4GL Console Window with file specification

build 'c:\windows\desktop\sample_program.spsrc' Building c:\windows\desktop\sample_program.spsrc ... Lines compiled: 11 (33000/min), code: 1KB

2.4.2 RUN

FORMAT:

RUN ['file_spec']

EXAMPLE:

To perform this example, open sample_program.spsrc inside SheerPower Rapid Development Environment. Click once on the Run icon in the toolbar to run the program. A menu will appear on your screen with three choices. Choose 'Exit', and the console window will appear.

Inside the console window, type 'RUN', and press [Enter]. The RUN command will cause the program to execute again, and the resulting menu created will appear.

Example 2-11 RUN command

run c:\sheerpower\sample_program.spsrc 14-Jul-2001 15:30

PURPOSE:

The RUN command is used to execute a program after it has been written inside SPDEV. This way you can remain inside the SP4GL Console Window and run your program after you experiment with elements of your program.

The RUN command can be used:

• after previously running the program from SPDEV by pressing the RUN icon in the toolbar.
• after building the program within the console window using the BUILD command.

DESCRIPTION:

The RUN command executes programs. RUN with no file specification runs the current program.

When SheerPower executes the RUN command, SheerPower displays a header with the program name, current date and time. SheerPower then executes the program.

A file specification can be given with the RUN command. If a file specification is provided, SheerPower searches for the file, loads it, and then runs it. If no file type is given, SheerPower will use the default file type .SPSRC.

Example 2-12 RUN command with file specification

run 'sample_program' c:\sheerpower\sample_program.spsrc 14-Jul-2001 15:30

Choose 'Exit' from the menu to complete running the program, then close the SP4GL Console Window.

If you are running a program that is not stored inside the SheerPower folder, you must specify the path (location) of the program.

FORMAT:

LIST [routine_name, routine_name, ...]

EXAMPLE:

To perform the following example, open the console window by clicking once on the SP4GL Console Window icon in SPDEV. Use the BUILD command to build the sample program (sample_program.spsrc). Then use the LIST command to display all the lines in the program.

Example 2-13 Listing program lines

build 'sample_program.spsrc' Building c:\sheerpower\sample_program.spsrc ... Lines compiled: 11 (33000/min), code: 1KB list c:\sheerpower\sample_program.spsrc 06-Jul-2001 16:29 do line input menu '"Calculator" = calc,"DOS Prompt" = dos,"EXIT"': ans$ if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop

PURPOSE:

Use the LIST command to display all or part of your program source code.

DESCRIPTION:

LIST displays lines from the current program. The listing includes a header with the program name, current date and time. LIST by itself lists the entire program, including routine headers and comment lines.

Specific sections of a program can be listed by referencing the program's routines. You can also list combinations of routines. For example:

list do_input	lists the lines of code under the routine "do_input"
list date_routine	lists the lines in the "date_routine" routine
list do_input, date_routine	lists the lines from both routines

If a routine is specified which does not exist, nothing is listed.

You can use the LIST command:

• after previously running the program from SPDEV by pressing the RUN icon in the toolbar.
• after building the program within the console window using the BUILD command.

FORMAT:

HALT

EXAMPLE:

Open SPDEV by clicking on the SPDEV shortcut icon on your desktop.

Open the sample program file sample_program.spsrc inside SPDEV by clicking on the Open icon inside the SPDEV toolbar.

Insert the HALT statement into the sample_program.spsrc source code as shown below.

Then run the program by clicking once on the Run icon in SPDEV.

Example 2-14 HALT statement

do line input menu '"Calculator" = calc,"DOS Prompt" = dos,"EXIT"': ans$ halt //<--- insert HALT statement here if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop

Choose 'Calculator' from the menu. The following will appear inside the SP4GL Console Window:

Halt at MAIN.0003 -- Call Stack Depth: 0 MAIN.0003 halt -- Recently Called Routines --

Keep the SP4GL Console Window open to continue with the next HALT statement example.

PURPOSE:

HALT is used to interrupt program execution, check values, and then continue execution.

The HALT statement must be inserted inside the source code before running the program. The HALT statement works the same way as the BREAK statement except that it always interrupts program execution. The BREAK statement will only interrupt program execution while DEBUG is ON. For a detailed explanation of the BREAK statement, please see Section 2.5.7, BREAK Statement.

DESCRIPTION:

HALT interrupts program execution, but it does not close any files, nor does it write the active output buffer. Once halted, the user can then check values, enter debug commands or any SheerPower statements and expressions. Execution can be continued with the GO command.

You can continue to run the sample program in the console window as follows:

Halt at MAIN.0003 -- Call Stack Depth: 0 MAIN.0003 halt -- Recently Called Routines -- print ans$ <--- type this line in and press [Enter] CALC go<--- type in 'GO' and press [Enter]

The calculator program will appear when your program resumes execution. To exit the program, choose 'Exit' in the menu, then close the console window.

FORMAT:

SHOW FILES

EXAMPLE:

To perform the following example, open the console window by clicking once on the SP4GL Console Window icon in SPDEV. Have the HALT statement inside the program. The show files command is generally used after a HALT statement halts a program's execution.

line input menu '"Calculator" = calc,"DOS Prompt" = dos,"EXIT"': ans$ halt if _exit then exit do select case ans$ case 'CALC' pass nowait: 'calc' case 'DOS' pass nowait: '$$' end select loop

Use the BUILD command to build the sample program (sample_program.spsrc). Then use the RUN command to run the program.

Example 2-15 Show files after using the HALT command

build 'sample_program.spsrc' Building c:\sheerpower\sample_program.spsrc ... Lines compiled: 11 (33000/min), code: 1KB run

PURPOSE:

Use the SHOW FILES command after a program halts to display a list of all open files and their status.

DESCRIPTION:

SHOW FILES displays a list of all open files and their status. If the files are ARS files (tables) then it some information will be displayed about their key structure, and recordsize, etc.

FORMAT:

GO

EXAMPLE:

Copy/Paste or type the following example into a new file inside SPDEV. Name it 'test.spsrc'.

Example 2-16 GO command

debug on for i = 1 to 6 print i if i = 4 then halt next i end

Run the program by clicking once on the Run icon.

The following result will appear in the console window:

1 2 3 4 Halt at MAIN.0003 -- Call Stack Depth: 0 MAIN.0003 if i = 4 then halt -- Recently Called Routines --

PURPOSE:

GO is used to continue a program after it has been interrupted.

DESCRIPTION:

GO resumes program execution after it has been interrupted. Once execution has stopped, you can enter immediate mode and debug commands, change code, etc. GO lets you resume execution even after changing code. If a HALT or BREAK statement was used, execution resumes at the first statement after the halt or break.

Type in the PRINT command as shown below inside the console window, and press [Enter]. The value will be printed out as requested. You can then type the GO command in the console window and press [Enter]. The program will then resume execution.

1 2 3 4 Halt at MAIN.0003 -- Call Stack Depth: 0 MAIN.0003 if i = 4 then halt -- Recently Called Routines -- print sqr(i)//<---- type in this line and press [Enter] 2 go //<---- type in 'go' and press [Enter] 5 6

SheerPower detects and announces exceptions and build errors. Sometimes errors occur which do not prevent execution, but do cause a program to execute incorrectly. SheerPower provides a high-level DEBUG system for detecting these more subtle errors.

DEBUG ON enables SheerPower's Debug System. DEBUG OFF disables the system.

The related function for the SheerPower Debug System is _DEBUG. See Section 6.8.1 for information on the _DEBUG system function.

Some DEBUG features automatically switch DEBUG ON or OFF when they are executed. Others require that DEBUG be enabled. (See DEBUG ON.)

Here is a list of SheerPower's DEBUG System features that require DEBUG to be enabled:

• TRACE ON and OFF
• STATS ON and OFF
• LIST STATS
• BREAK
• STEP

*Unlike most languages, SheerPower's debugging environment does not noticeably slow down program execution.

DEBUG ON/OFF

2.5.1 DEBUG ON

FORMAT:

DEBUG ON

The following example shows how the DEBUG ON statement is used inside an .SPSRC program to enable SheerPower's debug facility.

EXAMPLE:

Example 2-17 DEBUG ON

debug on print '1', print '2', break print '3', print '4', print '5' end 1 2 break at main.0003

PURPOSE:

DEBUG ON is used to enable SheerPower's debug system. SheerPower's debug system helps locate problems in the way a program runs.

DEBUG must be enabled in order to use its features. When DEBUG is enabled, all of SheerPower's debug features are available.

DESCRIPTION:

DEBUG ON can be issued in immediate mode or as a statement in a program.

If DEBUG ON is used as a statement in a program, SheerPower enables DEBUG when it encounters the statement. DEBUG remains enabled until a DEBUG OFF command or statement is executed or until a DEBUG feature is executed which disables it.

FORMAT:

DEBUG OFF

EXAMPLE:

debug off

PURPOSE:

DEBUG OFF is used to disable SheerPower's DEBUG system. Set DEBUG OFF when you have finished correcting your program.

DESCRIPTION:

DEBUG OFF can be issued in immediate mode or as a statement in a program. If DEBUG OFF is used in a program, SheerPower disables DEBUG when it encounters the DEBUG OFF statement.

DEBUG will remain disabled until a DEBUG ON statement is executed, or until a DEBUG feature is executed which enables it.

FORMAT:

TRACE ON|OFF

EXAMPLE:

Example 2-18 TRACE ON/OFF

debug on trace on do_totals trace off stop routine do_totals print "Doing totals..." end routine Doing totals...

PURPOSE:

In complex applications, there is often a need to follow an application's program flow in order to figure out how the application works. This is also useful when debugging logic errors in an application.

DESCRIPTION:

TRACING is used to follow an application's logic flow. As each statement is executed, the trace window will display the label and line number and source line being executed.

To turn off tracing, just close the trace window. TRACE OFF will stop tracing, but leave the trace window open.

You can copy select or all of the text inside the trace window by highlighting the text with your mouse (CTRL/A will select all) and using CTRL/C to copy it.

In the console window toolbar, you can use the Trace icon to toggle the trace feature on or off.

The STATISTICS Features

STATISTICS records information on a program's execution. It records the time each program line takes to execute and the number of times the line is executed. The word "STATISTICS" can be abbreviated to "STATS" (STATS ON, STATS OFF, LIST STATS). This abbreviation will be used frequently in this Guide.

FORMAT:

STATS ON

EXAMPLE:

Example 2-19 STATS ON

debug on stats on dim name$(5) for i = 1 to 5 input 'Please enter your name': name$(i) if _exit then exit for print 'Hello, '; name$(i); '!' next i end Please enter your name? Tester Hello, Tester! Please enter your name? exit <---- type in 'exit' and press [Enter]

PURPOSE:

STATS ON is used to turn on the statistics feature, which stores the execution time and count for each program line. Use STATS to tell if statements are being executed the correct number of times and which parts of a program are taking the most time. STATS is especially useful for speeding up a program's execution time.

DESCRIPTION:

STATS ON enables SheerPower's statistics feature. SheerPower begins recording statistics when program execution begins. The statistics feature remains enabled until the STATS OFF statement is executed.

STATS ON can be executed in immediate mode or in a program. If STATS ON is executed in immediate mode, DEBUG is automatically switched on. If STATS ON is executed in a program, and DEBUG is off, SheerPower ignores the statement. When STATS ON is executed, any statistics previously recorded are lost.

FORMAT:

STATS OFF

EXAMPLE:

stats off

PURPOSE:

STATS OFF is used to turn off the statistics feature.

DESCRIPTION:

STATS OFF turns off SheerPower's statistics feature. STATS OFF can be executed in immediate mode or in a program. If STATS OFF is executed in a program and DEBUG is off, SheerPower ignores the statement. STATS OFF leaves DEBUG on.

FORMAT:

LIST STATS [: routine_name, routine_name ,....]

EXAMPLE:

Example 2-20 Listing statistics in DEBUG system

debug on stats on dim name$(5) for i = 1 to 5 input 'Please enter your name': name$(i) if _exit then exit for print 'Hello, '; name$(i); '!' next i end Please enter your name? Tester <--- type name in, press [Enter] Hello, Tester! Please enter your name? Tester <--- type name in, press [Enter] Hello, Tester! Please enter your name? Tester <--- type name in, press [Enter] Hello, Tester! Please enter your name? Tester <--- type name in, press [Enter] Hello, Tester! Please enter your name? exit <--- type in 'exit', press [Enter]

Once you have run the program with the STATS ON, you can use the LIST STATS feature. Type in LIST STATS at the prompt, and the console window will display the file name, the date and time of day, and the statistics for each line in the program.

list stats c:\sheerpower\list_stats.spsrc 04-SEP-2003 12:46 debug on 1 0.00 stats on 1 0.00 dim name$(5) 1 0.00 for i = 1 to 5 5 20.55 input 'Please enter your name': name$(i) 5 0.00 if _exit then exit for 4 0.00 print 'Hello, '; name$(i); '!' 4 0.00 next i 1 0.00 end stats off <--- type in to turn off STATS debug off <--- type in to turn off DEBUG

PURPOSE:

LIST STATS is used to display the statistics recorded by the STATISTICS feature.

DESCRIPTION:

LIST STATS lists each program line along with the number of times the line was executed and the execution time of each line.

The far left column lists the number of times each statement was executed. The next column gives the time each statement took to execute. The time is given in seconds and fractions of a second. (0.01 means the program line was executed in one-one hundredth of a second.) The last column lists the program itself. STATS must be ON for LIST STATS to be executed.

All the options available with the "LIST" statement are also available with LIST STATS. (See Section 2.4.3, LIST for more information.)

FORMAT:

BREAK

EXAMPLE:

Example 2-21 Using BREAK in DEBUG system

debug on print '1', print '2', break print '3', print '4', print '5' end 1 2 break at main.0003

PURPOSE:

BREAK is used to stop program execution when DEBUG is ON. For instance, you might use BREAK to stop the program if a variable is assigned a wrong value.

DESCRIPTION:

The BREAK statement can be used anywhere in a program. The BREAK statement will not take effect unless DEBUG is turned on. If DEBUG is off, SheerPower ignores any BREAK statements.

The HALT statement works the same way as the BREAK statement (see Section 2.4.4, HALT Statement) except that it always interrupts program execution.

When SheerPower executes a BREAK statement, it interrupts program execution and prints a BREAK message. The BREAK message tells what line the break occurred in. Program execution can be continued with the GO or STEP commands.

FORMAT:

STEP [number]

EXAMPLE:

Example 2-22 Using STEP in DEBUG system

run 1 2 break at main.0003 step 2 3 4

PURPOSE:

STEP is used to execute a specific number of program statements and then stop execution. That way, you can "step through" your program to find bugs.

DESCRIPTION:

STEP is used to step through a program---to execute a specified number of program statements. DEBUG must be ON for the STEP command to take effect. If DEBUG is not on and the STEP command is given, SheerPower ignores it. STEP must be given as a command. When the STEP command has been executed, SheerPower issues a BREAK and prints the break message. Issuing the STEP command without a number causes SheerPower to execute one program line.

Issuing the STEP command with a number causes SheerPower to execute the number of program lines specified. SheerPower begins executing program lines from the last line executed. It stops when the number of lines specified have been executed or when program execution ends.

You must start a program with RUN before you can use the STEP command.

In the console window the mouse can be used to select (highlight) text on the screen.

Below is a table containing the special keystrokes available when working in the console window.

Table 2-1 SP4GL Console Window Keystrokes

Keystroke	Function Performed
ctrl/a	selects all text (both on and off screen)
alt/b	causes program execution to HALT
ctrl/c	places selected text into the clipboard
ctrl/m	places contents of message history into the clipboard
ctrl/t	places contents of screen (including scroll buffers) into the clipboard

This chapter describes the basic elements that make up a SheerPower program. It also describes the types of data used with SheerPower programs and how the data is processed.

3.1 Storing SheerPower Programs

SheerPower programs have a default extension of .SPSRC. It is recommended that you use this extension for all of your SheerPower programs. SheerPower source programs are saved as text files. You can edit SheerPower source programs with any text editor.

3.2 SheerPower Program Elements

A program is a series of instructions. These instructions describe how to manipulate data to produce a desired result. You determine what data the program will manipulate, how the program will manipulate it, and what the results of these manipulations will be.

When you create a program, you must use instructions that SheerPower understands. The SheerPower language provides these instructions. The language consists of statements. These statements are something like the words in this manual. You put them together in a meaningful order and SheerPower executes the program you write. Here is an example of a SheerPower program:

Example 3-1 SheerPower program example

input 'Please enter your name': name$ print 'Hello, '; name$ print 'Today is '; day$ print name$; ', have a good '; day$ end

The INPUT statement tells SheerPower to ask for a name. The PRINT statements tell SheerPower to print the information. END tells SheerPower it has reached the physical end of the program.

3.2.1 PROGRAM

FORMAT:

PROGRAM prog_name

EXAMPLE:

Example 3-2 Program statement

program display_name input 'Please enter your name': name$ print 'Hello, '; name$ end

PURPOSE:

The PROGRAM statement is used to name your program.

DESCRIPTION:

PROGRAM is used to name programs. prog_name is the program name. The program name must meet the following specifications for variable names:

• start with a letter
• can consist of letters, numbers, and/or underscore characters '_'
• can be up to, but not longer than, 39 characters

With SheerPower, when you execute this program, it will look like this:

Please enter your name? Tester <---type your name here then press [Enter] Hello, Tester

3.2.2 SheerPower Reserved Words

When you run the next program example, you will notice that the day is not asked for. DAY$ is a reserved word that SheerPower uses for storing the day. There are several other reserved words that SheerPower uses. You can refer to Appendix B, Reserved Words to see a complete list of the reserved words.

Example 3-3 SheerPower Reserved Words

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

3.3 SheerPower Program Structure

SheerPower programs are modular in structure. Every program can be divided into program units. The main unit is the main body of the program. This unit begins with the first program line and ends with the END statement.

first program line -- input 'Please enter your name': name$ print 'Hello, '; name$ print 'Today is '; day$ print name$; ', have a good '; day$ end statement -- end

FORMAT:

END

EXAMPLE:

Example 3-4 END statement

input 'Please enter your name': name$ print 'Hello, '; name$ end Please enter your name? John Hello, John

PURPOSE:

The END statement is used to mark the physical end of a program. It should be the last line of your program.

DESCRIPTION:

The END statement marks the end of a program. When SheerPower executes the END statement, it writes all active output buffers and closes all files in the current program.

3.3.2 STOP

FORMAT:

STOP

EXAMPLE:

Example 3-5 STOP statement

input 'Please enter your name': name$ input 'How old are you': age if age < 1 then print 'Not a valid age' stop end if print name$; ' is'; age end Please enter your name? Ted How old are you? .5 Not a valid age

PURPOSE:

STOP is used to terminate program execution where you do not want to mark the physical end of your program.

DESCRIPTION:

STOP behaves exactly as the END statement does. However, STOP does not mark the end of a program.

The STOP statement does not have to be the last physical line in a program. If there are subprograms, functions, etc., they can physically follow the STOP statement.

The STOP statement:

• closes all files
• closes all structures
• ends program execution

FORMAT:

[PRIVATE] ROUTINE routine_name [: private varname, ...] --- --- block of code --- [REPEAT ROUTINE] --- [EXIT ROUTINE] END ROUTINE

EXAMPLE:

Example 3-6 ROUTINE/END ROUTINE statements

get_username stop routine get_username input prompt 'Username: ': uname$ if _back or _exit then exit routine end routine Username: Tester

PURPOSE:

ROUTINES are block-structured subroutines. They provide a convenient way to name a block of code. By default, all variables in the main program are available inside the routine. To specify private variables that are not part of the main program use the PRIVATE option. To cause all variables inside of a routine to be treated as private, make the routine a PRIVATE ROUTINE.

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

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":

• routines -- All variables in the main code are available from within the routine. This form of ROUTINE is designed to make it quick and easy to segment long pieces of source code into smaller, easy to maintain, "code chunks".
  
• private routines -- All variables are private to the routine. Main code variables are accessable by prefixing the variable with MAIN$---for example: "main$xyz" references the main code variable called "xyz". This form of PRIVATE ROUTINE is designed to make it easy to write reusable routines to be included into any number of applications.

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".

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.

FORMAT:

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

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.

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.

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 ! !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

3.7.3 The (//) with Line Continuation

The double-forward slash can be used after an ampersand to document continued lines. When a line is continued with an ampersand, any comments must follow the ampersand. For example:

Example 3-23 Comments with line continuation

input a$ if a$ = '' then print a$; & // here is the trailing ' is OK.' // comment text end

3.8 Debug Comments in SPDEV

Code that is inserted into a program for the sole purpose of debugging the program should be marked with a debug comment. SheerPower can automatically create a debug comment line for you with a special keystroke.

The GOLD/C keystroke is mapped to create a debug comment line. In SPDEV, a GOLD key is a special key that allows you to utilize other keys for different purposes. The GOLD key is either the [Esc] (Escape) key or the [NumLock] (Numbers Lock) key. See Appendix F, Keystrokes for SheerPower Rapid Development Environment for more special SheerPower Rapid Development Environment keystrokes.

To perform a GOLD/C keystroke, place the cursor where you want the debug comment line created. Press once on the [Esc] key or the [NumLock] key. Let go and look in the bottom right hand corner of the SPDEV window. SheerPower tells you if your GOLD key is activated by highlighting a small square in the bottom frame in black, with gold letters that say 'Gol'. Now you can press the [C] key, and a small dialog box will appear asking you for your initials. Leaving your initials will allow future programmers (as well as yourself) to know who inserted this line of debug code. Enter your initials, and click on 'OK'.

Example 3-24 Debug comments

!++ debug sw June 08, 2001

The '!++' at the beginning of every line of debug comment makes it very easy to perform a search and find all lines containing debug code.

The following sections describe the directives that are available for use in your programs. These directives are invoked when the compiler builds a program and/or when a program is compiled.

FORMAT:

%COMPILE 'quoted_text'

EXAMPLE:

Example 3-25 %COMPILE program directive

print 'This is a test program.' %compile 'Text that you want to be seen inside the SPRUN file...' %compile 'Up to 100 lines of text can be seen here!' end

DESCRIPTION:

Using the DEPLOY feature you can make portable runnable applications (.SPRUN files). These files are plain text, and can be password protected.

SPRUN files allow you to distribute SheerPower programs without your source code being seen.

An SPRUN file can be easily copy/pasted, emailed or embedded into a website. This allows for simple distribution of an application.

The %compile text is truncated at 72 characters. There can be up to 100 %compile text lines in a program.

Once the text is inside the SPRUN file, if it is altered in any way the SPRUN file will not run! This is a good place to put copyright notices and license agreements, etc.

FORMAT:

%MESSAGE 'quoted_text'

EXAMPLE:

Example 3-26 %MESSAGE program directive

%message 'Including HELP module' %include 'sptools:help' end

DESCRIPTION:

This compiler directive displays a message, quoted_text, on the message line. The message is displayed when a program is built into a workspace or compiled.

FORMAT:

%MESSAGE ERROR: 'quoted_text'

EXAMPLE:

Example 3-27 %MESSAGE ERROR program directive

%message error: 'Using experimental HELP module' %include 'sptools:help' end

DESCRIPTION:

This compiler directive makes an alert sound and displays the message when a program is compiled.

FORMAT:

%INCLUDE 'file_spec'

EXAMPLE:

Example 3-28 %INCLUDE program directive

%include 'sptools:example'

PURPOSE:

%INCLUDE allows you to put common subroutines into a separate file to be shared among applications.

DESCRIPTION:

%INCLUDE includes a source code into the current SheerPower program. The default extension for the included file is .SPINC.

3.9.5 %INCLUDE CONDITIONAL

FORMAT:

%include conditional: 'file_spec'

DESCRIPTION:

If the file to be included does not exist, no error is generated. This allows programs to conditionally include modules.

%INCLUDE CONDITIONAL includes a source code file into the current SheerPower program if the file to be included is found. The default extension for the included file is .SPINC.

Programs manipulate data. The data can be numeric or textual, but the data must be presented according to the rules of the SheerPower language.

SheerPower accepts three basic types of data:

1. integer numbers
2. real numbers
3. string (textual) data

The following sections describe each of the three types of data.

An integer number is a whole number with no fractional part. The following are examples of integers:

+5% 894% -369004%

Integers can be positive or negative. Integer constants can end with a trailing percent sign (%). About integers:

• Names for integer variables, arrays or functions must be designated by a trailing percent sign (%) or declared with a DECLARE statement.
• A negative integer constant is designated by a leading minus sign.
• A positive integer constant can be designated by a leading plus sign or by the absence of a sign.
• Integers have a size of 32 bits.
• SheerPower allows integer numbers anywhere in the range of -2147483648 to +2147483647.

A real number can have a fractional part. The following are real constants:

5.4 894.0 -369004

Real numbers can be positive or negative. Any number that is not designated as an integer or a string is treated as a real number.

A real number without a decimal point is called an ambiguous constant. About real numbers:

• A variable, array or function whose name has no trailing % or $ is treated as a real number unless it is declared.
• A negative real constant has a leading minus sign.
• A positive real constant can have a leading plus sign or no sign.
• Ambiguous constants are treated as real numbers with a fractional part of 0 (5 = 5.0).
• Real numbers can have 18 digits to the LEFT of the decimal point, and 16 digits to the right. The largest number is: 999999999999999999.9999999999999999
• SheerPower REAL NUMBERS use a patent-pending "exact math" internal representation that avoids the "penny rounding" problems found in traditional programming languages.

Here is an example of SheerPower exact math:

Example 4-1 SheerPower Exact Math

x = 0 for i = 1 to 10000 x = x + .01 next i if x = 100.00 then print 'It is right.' It is right.

If you try this example in another programming language (Visual Basic or C++ for example), you will not get the correct answer. Here is another example:

Example 4-2 SheerPower Exact Math

print 123456789.012345 * 87654321.123456789 10821521028958940.344459595060205

4.1.3 String Data

String data consists of text. Text can consist of any characters. All of the following are valid string constants:

Example 4-3 String data

'Hello, Fred.' 'Account number (##-####)' '65'

About string data:

• String constants must be enclosed in single or double matching quotes. String variables must be designated by a trailing dollar sign ($) or declared with a DECLARE statement.
• The maximum size of a SheerPower 4GL string is 64 MB, or 67,108,864 bytes.
• String variables are dynamic in length.

Boolean variables represent either a TRUE or FALSE condition. These variables can be expressed with a trailing "?". For example:

Example 4-4 BOOLEAN variables

done? = FALSE do input 'Ready': ans$ if _exit then done? = true if _back then done? = true loop until done? end Ready? exit

4.3 Expressions

Expressions can be:

• constants
• simple variables
• array elements, which are a type of variable
• structure references, which are a feature of the SheerPower data structure system
• substrings
• compound expressions, which are any combination of the above operands separated by operators

A constant is a value that does not change during a program execution. Constants can be any of the three data types: integer numeric, real numeric or string.

Integer numeric constants are written with digits, with no decimal fraction. An integer constant can end with a percent sign. Examples:

235 412%

Real numeric constants are written with a sign, digits, and a decimal point. For example, 5.38 is a real numeric constant.

String constants must be enclosed in quotes. The quotes are called string delimiters. They tell SheerPower where the string begins and ends. The quotes are not considered part of the string. Everything within the quotes is considered part of the string. Note that the following strings are different:

Example 4-5 String constants and delimiters

print 'Account number (##-####)' print ' Account number (##-####)' end Account number (##-####) Account number (##-####)

An empty string is called a null string. A null string is indicated by a pair of quotes with nothing between them ("").

String delimiters can be single quotes (') or double quotes ("). However, the quotes must match and be paired.

Quotes can be included as part of a string by using them within the string delimiters. For example:

"Message'Time to go home!'"

The string part of this is:

Message 'Time to go home!'

The delimiter quotes can be used within a string by repeating them twice. For instance:

"Message ""Time to go home!"""

The string part of this is:

Message "Time to go home!"

Variables are a way of storing values that can change in the program during execution. A variable names a storage location. The value of the variable is stored in this location. Here are two types of variables:

• simple variables such as: AVERAGE and NAME$
• array elements such as: AVERAGE(3) and NAME$(2,12)

Two other constructs are used in ways similar to variables---you can use them in expressions and assign values to them:

• substrings such as: NAME$[7:12]
• structure references such as: SALES(AVERAGE) and CLIENT(PHONE)

Variables are represented by a name consisting of a letter or series of letters, numbers and underscore characters. Variables:

• must start with a letter
• can be followed by a proper data type designation (% for integers, $ for strings and ? for BOOLEANS)
• can be declared explicitly

Some examples of valid variables are:

TODAY$ X% Z INDEX

• Variables can be integer numeric, real numeric or string.
• Integer variables can contain only integer values.
• If a real numeric value is assigned to an integer variable, SheerPower rounds the real number and uses the resulting integer.
• String variable names can have a trailing dollar sign ($).
• If numeric data is assigned to a string variable, an exception occurs.

The following are examples of string variables:

TODAY$ X$ LAST_NAME$ ANSWER$

• A variable that is not followed by a $, % or ? is treated as a real numeric variable unless it is declared.
• If string data is assigned to a real numeric variable, an error will result.
• If integer data is assigned to a real numeric variable, SheerPower treats it as a real number with a fractional part of 0.

The following are examples of real numeric variables:

INDEX Z COUNTER AMOUNT

SheerPower uses the last assigned value when a variable is referenced. See Section 5.7, Private Variables in Routines, for more information on using variables.

An array is a variable that consists of a group of elements. Each element represents a storage location. A different value can be assigned to each element. Here is an example of an array:

QUANTITY(1) QUANTITY(2) QUANTITY(3) QUANTITY(4) QUANTITY(5)

To indicate which element to access, use numbers after the array name, called subscripts. The subscripts are enclosed in parentheses. Example: amount(3,2)

Subscripts must be given as integers. If a real numeric subscript is given, it will be rounded and the integer portion used. Arrays can contain real numeric, integer or string values. String and integer arrays are designated by placing the appropriate symbols after the array name and before the subscript. For example:

a$(5,10) a%(5,10)

About arrays:

• Arrays must be defined with the DIM statement and can be redefined with the REDIM statement.
• Arrays can have up to 32 dimensions.
• An array can have as many elements as memory allows.
• Integer and string arrays must be designated by the appropriate symbol (% for integers, $ for strings) or else they must be declared.
• Subscripts must be integers. Real subscripts are rounded.
• Multiple subscripts must be separated by commas.
• The default low bound for an array is 1 or the number indicated with the OPTION BASE statement (See Section 5.8.4).
• You can indicate the low bound explicitly with a TO clause:
  DIM COSTS(5 TO 10).

Substrings are a way to refer to a part of a string. The format of a substring is:

str_var [begin : end]

str_var is the name of a string variable. begin is the position in the string where your substring begins. end is the position at which the substring ends. For example, here is a string called ALPHABET$:

Example 4-6 Substrings

alphabet$ = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' print alphabet$[9:14] end IJKLMN

The substring ALPHABET$[9:14] tells SheerPower to begin at the ninth character and count to the 14th character. Everything between and including these two positions makes up the substring. Therefore, the substring is "IJKLMN".

begin and end are integers. If real numbers are given for these positions, SheerPower rounds them and uses the remaining integers. A substring can be manipulated like any other expression, and data can be stored in the substring. Substrings can be used also to change the value of a string. For example:

Example 4-7 Substrings used to change string value

let a$ = 'Your tests are in.' print a$ let a$[6:10] = 'results' print a$ end Your tests are in. Your results are in.

4.6 Structure References

Another type of variable is a structure reference. SheerPower includes a transparent interface to several record management systems, including the Windows file management system. One of the major features of SheerPower is its ability to perform database operations as a part of the language. SheerPower's data structure statements allow manipulation of stored data from within a user's programs. (See Chapter 15, Data Structure Statements for information on the SheerPower data structure statements.)

SheerPower stores data in structures. Structures look something like this:

Example 4-8 SheerPower data structure

FIELDS / | \ / | \ / | \ / | \ / | \ R | Client | Last name | First name E | Number | | C |---------|-----------------------------|-------------------- O _____ |8|0|5|4|3|C|a|s|s| | | | | | | | | | | |C|a|t|h|y| | | | | | R _____ |8|0|5|4|2|B|r|o|c|k| | | | | | | | | | |B|u|d| | | | | | | | D | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | S positions

Each structure is made up of records and fields. In the CLIENT structure above, we have a record for each customer.

Each record consists of fields. For example, our customer records might contain a field for the customer's ID number, last name, first name, address, phone number, company name, etc.. Each of these pieces of data is stored in its own field - the name field, address field, phone number field, etc.. These fields appear as columns in the example shown above.

The field data in structures can be referenced by using structure references. To reference a field, indicate the structure name and the expression of the field whose contents you want to access:

struc_name(field_expr)

struc_name is the name associated with the structure. field_expr is the name of a field in the structure. When a field is referenced, SheerPower searches the current record for this field and reads its contents. Some examples of structure references are:

CLIENT(PHONE) CATALOG(PART_NUM)

The field_expr can be either a string or numeric expression.

A string constant can be used to specify the field name. If the field name is given as a string constant, it need not be enclosed in quotes. SheerPower will use the string constant as the field name:

PRINT CL(LAST) / the field is specified by its field name

If the field is specified as an expression, the expression will need to be preceded by a pound sign (#). The pound sign tells SheerPower that the following characters are an expression, not the field name. If the pound sign is not included, SheerPower will interpret the characters as a field name. Here are two examples:

PRINT CL(#FIELDNAME$) / the field is specified by the variable FIELDNAME$ PRINT CL(#FIELDNUM) / the field is specified by the variable FIELDNUM

See Section 15.8.1.1, FIELD Expressions for an example of a program that uses field expressions.

Fields with multiple occurrences (single dimension array) are supported.

When defining a field with multiple occurrences, the length of the field must be the length of a single occurrence.

Each occurrence of a field is accessed by including the occurrence number in the field expression. For example, to access the second occurrance of the field "address":

print cust(address#2)

Compound expressions can be used in programs. Compound expressions consist of operators and operands. There are three types of compound expressions:

• numeric expressions
• string expressions
• conditional expressions

Numeric expressions consist of numeric (integer or real) variables, constants or expressions separated by arithmetic operators. The arithmetic operators are +, -, *, /, and ^.

Constants Variables + Add 4%+2% Z + TWO16 - Subtract 4%-2% Z - TWO16 / Divide 4%/2% Z / TWO16 * Multiply 4%*2% Z * TWO16 ^ Raise to a power 4%^2% Z ^ TWO16

Any number of these operators can be combined in an expression.

4 + Z ^ TWO16 Z * TWO16 / 2

Generally, two arithmetic operators cannot be used next to each other. However, a + or - sign can be used to indicate a positive or negative number. For example:

total * -2 = total * (-2) total / +2 = total / (+2)

If all the values in an arithmetic expression are of the same data type, the result of the expression will be of that data type. For example, if an expression consists only of integer numbers, it will yield an integer result. If an expression consists only of real numbers, the result will be a real number. If an expression consists of integers and real numbers, the result will be a real number. If the target of a real calculation is an integer (a% = 1.5 + 2.8), the result is rounded before it is assigned to the target.

String expressions are strings concatenated (joined). String expressions can be joined by a plus sign (+) or by an ampersand (&). SheerPower evaluates this type of string expression by concatenating the strings. For example:

Example 4-9 String expressions

z$ = 'MO' + 'TH' & 'ER' print z$ end MOTHER

In the above example, SheerPower joins the strings separated by a plus sign and an ampersand, and assigns their value to z$. String constants, variables, functions, etc. can be included in your expressions. For example:

Example 4-10 String expression with string variable

let last$ = ' is it.' print 'This' + last$ end This is it.

4.8.2.1 Conditional Expressions

Conditional expressions are expressions which yield a TRUE (1) or FALSE (0) value. Conditional expressions are created by using either relational or logical operators. When SheerPower evaluates a conditional expression, it returns a value of either TRUE or FALSE. If the expression is TRUE, SheerPower returns the integer 1. If the expression is FALSE, SheerPower returns the integer 0.

Relational operators are similar to those used in algebra. The relational operators are:

= equals X=Y X is equal to Y < less than X<Y X is less than Y > greater than X>Y X is greater than Y <= less than or equal to X<=Y X is less than or equal to Y >= greater than or equal to X>=Y X is greater than or equal to Y <> not equal to X<>Y X is not equal to Y

X and Y can be any unconditional or conditional expression.

When relational operations are performed on strings, SheerPower determines which string occurs first in the ASCII collating sequence and returns TRUE or FALSE. For instance, when you perform relational operations on two strings, SheerPower checks the ASCII values for each character in each string. SheerPower compares the strings character by character using these ASCII values, and determines where there is a difference in the values.

When SheerPower finds a character that differs, it compares the two and determines which one has a smaller ASCII code number. SheerPower then returns a TRUE or FALSE value depending on the relational expression. For example:

Example 4-11 Performing relational operations on strings

a$ = 'TEXT' b$ = 'TEST' MESSAGE$ = 'Strings are equal' if a$ < b$ then message$ = a$ + ' is less than ' + b$ if b$ < a$ then message$ = b$ + ' is less than ' + a$ print message$ end TEST is less than TEXT

SheerPower compares the two strings. They are identical up to the third character. The ASCII value of S is 53. The ASCII value of X is 58. Therefore SheerPower prints "TEST is less than TEXT".

The logical operators are:

NOT NOT X TRUE if X is false and FALSE if X is true. AND X AND Y TRUE if X and Y are true. OR X OR Y TRUE if X or Y is true. XOR X XOR Y TRUE if X is true, or if Y is true but FALSE if both X and Y are true. EQV X EQV Y TRUE if X and Y are true, or TRUE if X and Y are false, but FALSE otherwise. IMP X IMP Y TRUE if X is true and Y is false.

X and Y can be any expressions. Logical operators are usually used on integers or expressions which yield an integer result such as conditional expressions. Logical operators will always yield an integer result. If a logical operator is used on a real number, the real number is rounded and the resulting integer is used.

Logical expressions always return an integer value. If the integer value is a 1, the expression is TRUE. If the integer value is a 0, the expression is FALSE. (NOT 0 is equal to -1 and is TRUE. NOT 1 is equal to -2 and is FALSE.)

VALUE TRUE FALSE +--------------------------+ | 0 | | X | |-----------|------|-------| | 1 | X | | |-----------|------|-------| | NOT 0 (-1)| X | | |-----------|------|-------| | NOT 1 (-2)| | X | +--------------------------+

• If a logical operator is used on a real expression, the expression is rounded and the resulting integer value is operated upon.
• Integers are represented as a signed 32-bit quantity.

Logical operators can be used to do bit manipulation. Computers represent values in a binary code, using ones and zeros. SheerPower integer values are represented as a 32-bit binary longword. A bit which is set to 1 is considered on. A bit which is set to 0 is off. The value of the word is equal to the value of all the bits which are on, added together. For example:

0 0 0 1 0 1 1 1 = 16 + 4 + 2 + 1 = 23

The last bit has a value of 1. The second to the last bit has a value of 2. The third bit has a value of 4, the fourth a value of 8, the fifth bit has a value of 16, and so on. Each bit has a value double that of the previous one:

0 0 0 0 0 0 0 0 --------------------------------------------- 128 64 32 16 8 4 2 1

Bits can be manipulated and tested using logical operators. The logical operators work on bits. They compare each position in each word according to the particular rules of the logical operator. For instance, here is the AND operator used on two values:

Example 4-12 Bit manipulation

let a% = 23% // 00010111 let b% = 37% // 00100101 let c% = (a% and b%) print c% end 5

When SheerPower executes this program, it compares the two values. It sets a bit in the result to 1 (on) only if both the bits at a given position are on (1). The value of the resultant word is 5:

A% 0 0 0 1 0 1 1 1 = 23 B% 0 0 1 0 0 1 0 1 = 37 --------------- C% 0 0 0 0 0 1 0 1 = 5

When SheerPower evaluates an expression, it evaluates it in a specific order. SheerPower evaluates expressions from left to right.

1+Z+4 equals (1+Z)+4 1+Z-4 equals (1+Z)-4 3*4/QUANTITY equals (3*4)/QUANTITY 12/QUANTITY*3 equals (12/QUANTITY)*3

The following priorities take precedence over the left to right evaluation rule:

1. SheerPower always evaluates expressions in parentheses first. Parentheses, ( ), can be used to change the order of any of the following operations. If parentheses are nested, SheerPower evaluates them from the inside out. For example:

   Z%-(X% / (Y% + AMOUNT))

   
   SheerPower evaluates the expression Y% + AMOUNT first. Next, it divides the X% by AMOUNT to determine that result. Finally, it subtracts the entire sum from Z%.

2. SheerPower performs functions second.
3. SheerPower performs exponentiation.
4. SheerPower performs multiplication and division.
5. SheerPower performs addition and subtraction.
6. SheerPower performs relational operations from left to right. (The relational operators are: =, <, >, <=, >= and <>.) The only exception is the assignment of the result. The result is always assigned last.
7. SheerPower performs logical operations in the following order:
   

   NOT
   AND
   OR
   XOR
   IMP
   EQV

Parentheses are used around every set of operations. This makes it easy to pick out the beginning and end of an operation, and will make absolutely clear what is intended without depending on the order of precedence of operators. If someone reading the code can know with absolute certainty how it was intended to be executed via the use of parentheses, then they will not have to wonder if a particular bug is due to the language used creating the code, other than what was intended. See Appendix A, Coding Principles and Standards for more on Coding Principles and Standards in SheerPower.

if a > b * c or d + 4 = f then x = x + 1 <--- hard to read! if ((a>(b * c)) or ((d + 4) = f)) then x = x + 1 <--- clarity with parenthesis

Variables specify storage locations. Numeric and string variables are assigned values with the LET statement. String variables can also be assigned values with the LSET, RSET and CSET statements.

The LET statement assigns the value of an expression to a variable. The expression is evaluated and its value is stored in the location specified by the variable. The data types of the expression and the variable must match. Thus, you must assign a string variable string values and you must assign numeric variables numeric values. A string variable must end with a dollar sign "$" unless you declare it. An integer variable must end with a percent sign (%) unless you declare it.

The DECLARE statement allows you to dispense with data type designations. DECLARE declares a variable as either string, integer or real. Once the variable has been declared, you do not need to attach a $ or % to it. Functions, arrays, etc., can also be declared with the DECLARE statement.

FORMAT:

DECLARE [STRING | INTEGER | REAL | BOOLEAN | OBJECT] var, var...

EXAMPLE:

Example 5-1 DECLARE statement

declare string name, sex declare integer age declare real amount declare object anything declare boolean is_male input 'Enter your name': name input 'Enter your age': age input 'Enter your sex': sex input 'Enter an amount': amount if sex = 'male' then is_male = true else is_male = false print print name; ' is a'; age; 'year old '; sex print name; ' entered the amount'; amount if is_male then print name; ' is male' anything = 4 + 5 print 'This object (or dynamic) variable contains a numeric value: '; anything anything = 'kitty' print 'Now it contains a string value: '; anything end Enter your name? Sammy Enter your age? 28 Enter your sex? male Enter an amount? 25.38 Sammy is a 28 year old male Sammy entered the amount 25.38 Sammy is male This object (or dynamic) variable contains: 9 Now it contains a string value: kitty

PURPOSE:

DECLARE is used to specify the data types of variables, functions, etc. Once the data type of a variable or function has been declared, it is not necessary to designate them with a trailing $ or %.

DESCRIPTION:

DECLARE declares the data type of a variable or function. The STRING option indicates that the following are string variables or functions. INTEGER declares integer numeric. REAL indicates real numeric. The BOOLEAN option indicates that the following are Boolean variables. Only one of the four data type options can be used in each DECLARE statement. Any number of variables can be declared with a DECLARE statement.

DECLARE OBJECT declares one or more variables to be of type OBJECT. A variable of type OBJECT receives the data type of the data that is put into it.

Note OBJECT and DYNAMIC are synonyms in this statement. DECLARE DYNAMIC is the same as DECLARE OBJECT.

To find out the current data type of an object variable, the DTYPE function can be used (see Section 6.9.2).

Multiple data types can be declared by using the following format:

DECLARE datatype var, var, datatype var, var, datatype var, var, ...

For example:

Example 5-2 Declaring multiple data types

declare string name, sex, integer age, year, real amount input 'Enter your name': name input 'Enter your age': age input 'Enter your sex': sex input 'Enter the year': year input 'Enter an amount': amount print print name; ' is a'; age; 'year old '; sex; ' in'; year print name; ' entered the amount'; amount end Enter your name? Terry Enter your age? 25 Enter your sex? female Enter the year? 2000 Enter an amount? 582.69 Terry is a 25 year old female in 2000 Terry entered the amount 582.69

5.1.2 DECLARE STRUCTURE

FORMAT:

DECLARE STRUCTURE struc_name1 [, struc_name2 ...]

EXAMPLE:

Example 5-3 DECLARE STRUCTURE

declare structure str open structure cl: name 'sptools:client' ask structure cl: id cl_id$ set structure str: id cl_id$ extract structure str end extract for each str print str(#1); ' '; str(#2) next str end 20000 Smith 20001 Jones 20002 Kent 23422 Johnson 32001 Waters 43223 Errant 80542 Brock 80543 Cass 80544 Porter 80561 Derringer 80573 Farmer

DESCRIPTION:

DECLARE STRUCTURE declares one or more symbols to be of type STRUCTURE. Once a symbol has been declared to be of type STRUCTURE, it can be used in statements such as SET STRUCTURE...ID to write generalized routines where you do not know at compile time which structure you are going to use.

Usage example: this statement could be used in the situation where you have a transaction structure and a transaction history structure and, optionally, want a report on one or the other. You could use one report program and the DECLARE STRUCTURE statement to declare which structure to use when the user makes the report selection.

5.2 OPTION Statements

FORMAT:

OPTION REQUIRE DECLARE

EXAMPLE:

Example 5-4 OPTION REQUIRE DECLARE statement

option require declare declare string name, comment input 'Please enter your name': name line input 'Enter a comment in quotes': comment print name; ' says, '; comment end Please enter your name? George Enter a comment in quotes? 'Have a nice day!' George says, 'Have a nice day!'

DESCRIPTION:

OPTION REQUIRE DECLARE causes SheerPower to require all variables in the program to be declared. If the OPTION REQUIRE DECLARE statement is used and a variable is left undeclared, SheerPower will return an error when program execution is attempted. The OPTION REQUIRE DECLARE statement should occur before any DECLARE statements and before any variables are assigned.

FORMAT:

OPTION BASE [0 | 1]

DESCRIPTION:

OPTION BASE sets the lowest subscript or base for arrays. The base can be either zero or one. If you use OPTION BASE 0, the lowest element of an array has the subscript zero (0). If you use OPTION BASE 1, the lowest element is subscript one (1).

See Section 5.8.4 for an example and detailed information on this statement.

FORMAT:

[LET] var = expr

EXAMPLE:

Example 5-5 LET statement

input 'Last name': last$ input 'First name': first$ let name$ = first$ & ' ' & last$ print name$ end Last name? Taylor First name? Rick Rick Taylor

PURPOSE:

The LET statement is used to store information into a variable or data structure.

DESCRIPTION:

var is the variable being assigned a value. expr is an expression. The expression is evaluated and its result is assigned to the variable. The expression can be any SheerPower expression (see Chapter 4.) The variable and the expression data types must match. For instance, if var is a string variable, expr must be a string expression.

NOTE: The keyword LET is optional. For example:

LET name$ = first$ & ' ' & last$

can be stated as:

name$ = first$ & ' ' & last$

When SheerPower executes the LET statement, it first evaluates the expression on the right side of the equal sign. It then assigns this value to the variable on the left side of the equal sign. The variable represents a location in memory. The value of the expression is stored in this location. Each time a new value is assigned, the old value is lost and the new value is stored in its memory location.

Assigning numeric values:

• Assigning a numeric value to a string variable results in an error.
• Assigning a real value to an integer variable causes the real number to be rounded to the nearest integer and assigned.

Example 5-6 Assigning numeric values with LET statement

input 'Amount': amount let rounded% = amount print 'Real numeric amount:'; amount print 'Integer amount (after rounding):'; rounded% end Amount? 1.54 Real numeric amount: 1.54 Integer amount (after rounding): 2

Incrementing Numeric Variables

FORMAT:

num_var++

It is common place to increment a numeric variable:

total = total + 1 lines = lines + 1

SheerPower 4GL provides a shorthand syntax for incrementing numeric variables:

total++ lines++

• Assigning a string value to a numeric variable results in an error.
• String variables are dynamic in length, and can be assigned values of up to 12 million characters in length.

LSET, RSET and CSET assign string values to variables. LSET left-justifies, RSET right-justifies, and CSET center-justifies the new value. These statements can be used to assign only string values.

LSET, RSET and CSET justify the new value within the length of the previous value. For example, in the following program, HEADING$ has a length of twenty characters and consists of twenty dots:

Example 5-7 LSET, RSET and CSET

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$; ')' end (....................)

In the following example, the RSET statement is used to assign the new value 'Page 12' to HEADING$. SheerPower uses the current length of HEADING$, 20 characters, and replaces it with the new value, 'Page 12'. SheerPower right-justifies this value by padding it with 13 leading spaces. Thus, HEADING$ still has a length of twenty characters.

Example 5-8 RSET statement

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$; ')' rset heading$ = 'Page 12' print '('; heading$; ')' end (....................) ( Page 12)

5.4.2 LSET

FORMAT:

LSET str_var = str_expr

EXAMPLE:

Example 5-9 LSET statement

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$; ')' lset heading$ = 'Page 12' print '('; heading$; ')' end (....................) (Page 12 )

PURPOSE:

LSET is used to left-justify string data.

DESCRIPTION:

When SheerPower executes an LSET statement, it evaluates the string expression on the right side of the equal sign. SheerPower assigns the new value to the string variable and left-justifies this value within the length of the old value. If the new value has leading or trailing spaces, these spaces are carried over and the string is justified with those spaces. LSET can be used only with strings.

FORMAT:

RSET str_var = str_expr

EXAMPLE:

Example 5-10 RSET statement

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$ ;')' rset heading$ = 'Page 12' print '(' ; heading$ ; ')' end (....................) ( Page 12)

PURPOSE:

RSET is used to right-justify string data.

DESCRIPTION:

When SheerPower executes the RSET statement, it evaluates the string expression on the right side of the equal sign. SheerPower assigns the new value to the string variable and right-justifies this value within the length of the old value. If the new value has leading or trailing spaces, these spaces are carried over and the string is justified with those spaces. RSET can be used only with strings.

FORMAT:

CSET str_var = str_expr

EXAMPLE:

Example 5-11 CSET statement

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$; ')' cset heading$ = 'Page 12' print '('; heading$; ')' end (....................) ( Page 12 )

PURPOSE:

CSET is used to center string data.

DESCRIPTION:

When SheerPower executes the CSET statement, it evaluates the expression on the right side of the equal sign. Next, SheerPower assigns the new value to the string variable and centers it within the length of the old value. If the string value has leading or trailing spaces, the spaces are carried over and the string is centered with those spaces. CSET can be used only with strings.

5.5 LSET, RSET, CSET FILL

FORMAT:

LSET | RSET | CSET FILL str_expr: str_var = expr

EXAMPLE:

Example 5-12 LSET, RSET, CSET FILL statements

heading$ = repeat$('.', 20) // Twenty dots print '('; heading$; ')' cset fill '*': heading$ = 'Page 12' print '('; heading$; ')' end (....................) (*******Page 12******)

DESCRIPTION:

The value of expr is left-justified, right-justified or centered inside the str_var. The remaining part of the string is filled with the pattern specified by str_expr. If str_expr is the null string, no filling occurs---the remaining part of the string is left as is.

5.6.1 READ

FORMAT:

DATA [num_const | str_const] [,[num_const | str_const]...] . . . READ [num_var | str_var] [,[num_var | str_var]...]

EXAMPLE:

Example 5-13 DATA, READ, RESTORE Statements

dim months$(6) data January, February, March data April, May, June for i = 1 to 6 read months$(i) print months$(i) next i end January February March April May June

PURPOSE:

DATA and READ statements are used to assign data to variables in cases where the data will not change with successive runs of the program.

DESCRIPTION:

The DATA and READ statements assign data to variables. DATA specifies a list of data to assign. The data must be given as constants and can be string, numeric or integer types. Multiple data items must be separated by commas.

The READ statement specifies a list of variables to assign data to. The variables can be string, numeric or integer variables. They can be substrings, array elements, etc..

When SheerPower executes the first READ statement, it goes to the first DATA statement and assigns the items in the DATA list to the variables in the READ list. The first variable in the READ list is assigned the first value in the DATA list. The second variable in the READ list is assigned the second value in the DATA list, and so on.

DATA constant, constant, constant, constant... . . | | | | . READ variable, variable, variable, variable...

If the data item contains a comma, the data item should be enclosed with single or double quotes. For example:

Example 5-14 DATA items containing commas

dim amounts$(3) data '$25,000', '$250,000', '$2,500,000' read amounts$(1), amounts$(2), amounts$(3) print amounts$(1), amounts$(2), amounts$(3) end $25,000 $250,000 $2,500,000

The variable types and data types must match or an exception will result. For example, if the third item in the DATA list is a string constant, and the third variable in the READ list is a numeric variable, an exception will result.

When the second READ statement is executed, SheerPower starts reading from the first unread data item in the DATA list. For example:

Example 5-15 DATA and READ statements

dim months$(4) data January, February, March, April, May, June read months$(1), months$(2) read months$(3), months$(4) print months$(1), months$(2), months$(3), months$(4) end January February March April

In the example above, when the first READ statement is executed, SheerPower reads the months January and February. When the second READ statement is executed, SheerPower will continue at the first unread month---March---and read it into months$(3).

If you attempt to read more data than exists; that is, if your READ list has more items than your DATA list, an exception will result. You can avoid this by using the RESTORE statement to restore the DATA list and read from the beginning again.

The READ and DATA statements must occur in the same program unit. For example, you cannot not have your DATA statements in the main program unit and your matching READ statements in a subprogram.

See Section 5.6.2 for information on using RESTORE.

FORMAT:

RESTORE

EXAMPLE:

Example 5-16 RESTORE statement

dim months$(3) dim more_months$(3) data January, February, March for i = 1 to 3 read months$(i) print months$(i) next i restore print for i = 1 to 3 read more_months$(i) print more_months$(i) next i end January February March January February March

PURPOSE:

RESTORE is used to access the same set of data (from a DATA statement) for a number of READ statements.

DESCRIPTION:

RESTORE restores the DATA statements in a program unit so they can be used again. When the RESTORE statement is executed, all the DATA statements which have been read are restored. The next READ statement causes SheerPower to go back to the first DATA statement and begin assigning the items in its list.

In the example program, the months will be read and assigned to the array MONTHS$. When the RESTORE is executed, the DATA statements will be restored. When the READ statement is executed, the months will be read into the new array MORE_MONTHS$.

FORMAT:

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

EXAMPLE:

Example 5-17 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.

Arrays are a type of variable. They are used to store and manipulate tables of variable information. An array must be defined before it is used in a program. Array variables are described in Section 4.5.1, Arrays.

Arrays are dimensioned with a DIM statement. The REDIM statement can be used to redimension an array; that is, to change the dimensions of an array which has been defined with the DIM statement. The OPTION BASE statement changes the default low bound. By default, the low bound is 1.

About arrays:

• The highest bound allowed is 2147483648.
• The lowest bound allowed is -2147483647.
• Each array can have up to 32 dimensions.
• See Section 4.5.1, Arrays for more information on the storage allocation of arrays.
• If an array element outside of the specified bounds is referenced, an exception is generated.

FORMAT:

DIM [INTEGER | REAL | STRING | BOOLEAN] array_name ([int_expr TO] int_expr [, ...])

EXAMPLE:

Example 5-18 DIM statement

dim name$(4) for i = 1 to 4 input 'Enter a name': name$(i) next i print for i = 1 to 4 print i; ' '; name$(i) next i end Enter a name? Jim Enter a name? Jane Enter a name? Bob Enter a name? Betty 1 Jim 2 Jane 3 Bob 4 Betty

PURPOSE:

DIM is used to dimension arrays. Arrays are used to store tables of variable information. An array must be dimensioned before it can be used.

DESCRIPTION:

The simplest version of a DIM statement is:

DIM array_name(int_expr)

array_name is the name of the array being defined. The array name must meet the rules for variable names. int_expr is the high bound for the array---the highest element allowed in a dimension. The low bound is the lowest element allowed in a dimension. The low bound defaults to 1. For example:

DIM NAME$(4)

This statement defines a one-dimensional array with four elements:

NAME$(1) NAME$(2) NAME$(3) NAME$(4)

Multiple Dimensions

An array can have up to 32 dimensions. A high bound must be specified for each dimension.

DIM array_name(int_expr [, int_expr, ...])

For example:

dim name$(4,2)

This statement defines the following two-dimensional array:

NAME$(1,1) NAME$(1,2) NAME$(2,1) NAME$(2,2) NAME$(3,1) NAME$(3,2) NAME$(4,1) NAME$(4,2)

Low Bounds

The low bound is the lowest element a dimension can have. Low bounds can be specified for each dimension of an array. If no low bound is specified, the default is 1. To specify a low bound, use the following format:

DIM array_name (int_ expr TO int_expr)

The number preceding TO is the low bound. For example:

dim name$(4,18 to 20)

This statement creates an array whose first dimension contains elements 1-4 and whose second dimension contains elements 18-20:

NAME$(1,18) NAME$(1,19) NAME$(1,20) NAME$(2,18) NAME$(2,19) NAME$(2,20) NAME$(3,18) NAME$(3,19) NAME$(3,20) NAME$(4,18) NAME$(4,19) NAME$(4,20)

FORMAT:

REDIM array_name (int_expr, int_expr...) ... OR REDIM array_name [( [int_expr TO] int_expr, [int_expr TO] int_expr... )] ...

EXAMPLE:

Example 5-19 REDIM statement

dim name$(2) input 'How many names': num redim name$(num) for i = 1 to num input 'Enter a name': name$(i) next i do print for i = 1 to num if name$(i) = '' then print i; ' '; 'empty slot' else print i; ' '; name$(i) end if next i print input 'How many names': num if _back or _exit then exit do redim name$(num) loop end How many names? 3 Enter a name? Tim Enter a name? Sammy Enter a name? Fred 1 Tim 2 Sammy 3 Fred How many names? 4 1 Tim 2 Sammy 3 Fred 4 empty slot How many names? exit

PURPOSE:

The REDIM statement is used to change the size of an array.

DESCRIPTION:

REDIM redimensions arrays. REDIM can be used only on arrays that have already been dimensioned with the DIM statement. The REDIM statement has the same rules, options and limits as the DIM statement.

Arrays can be dynamically expanded as needed. If you REDIM a single dimension array or the first dimension of a multi-dimensioned array to a larger size, the old values are kept. If you REDIM any array to a smaller size or REDIM two or more dimensions in a multi-dimensioned array to a larger size, the old values are lost.

If your application depends on REDIM initializing all array values, change your code as follows:

Old Code: REDIM X(100) New Code: REDIM X(1) REDIM X(100)

The REDIM X(1) forces all array values to be initialized by the second REDIM statement.

FORMAT:

OPTION BASE [0 | 1]

EXAMPLE:

Example 5-20 OPTION BASE statement

option base 0 dim name$(4) for i = 0 to 4 input 'Enter a name': name$(i) print i; ' Hello, '; name$(i) next i end Enter a name? June 0 Hello, June Enter a name? Tony 1 Hello, Tony Enter a name? Sandy 2 Hello, Sandy Enter a name? Carl 3 Hello, Carl Enter a name? Liz 4 Hello, Liz

PURPOSE:

OPTION BASE is used to set the default low bound for arrays to suit your needs. You have the option of starting the array with element O or element 1.

DESCRIPTION:

When no low bound is specified for a dimension, the default is 1. The OPTION BASE statement lets you specify a default low bound of 0 or 1. When any following DIM or REDIM statements are executed, SheerPower defaults the low bound to 0 or 1 as specified.

SheerPower has numerous built-in functions. This chapter describes the system and other built-in functions.

6.1 Common Math Functions

The following are common math functions that SheerPower performs:

CEIL(x) returns the ceiling of x. The ceiling of x is equal to the smallest integer that is not less than x.

Example 6-1 CEIL function

print ceil(1.543) 2

6.1.2 DIV0(num_expr1, num_expr2)

The DIV0 function divides num_expr1 by num_expr2. If num_expr2 (divisor) is 0, 0 is returned.

Example 6-2 DIV0 function

print div0(0.8, 0.000004) print div0(0.8, 0.0) print div0(6, 3) print div0(6, 0) end 200000 0 2 0

6.1.3 FP(num_expr)

Given a number, the FP function returns the fractional part of the number. See Section 6.1.6, IP(num_expr).

Example 6-3 FP function

print fp(238.304) .304

6.1.4 INT(num_expr)

INT returns the whole portion of a real number as a real number.

Example 6-4 INT function

print int(148.8432) 148

6.1.5 INTEGER(num_expr)

INTEGER changes any numeric expression into an integer value and assigns the integer value to the variable specified.

Example 6-5 INTEGER function

z = integer(4 + (993 * 35)) print z end 34759

6.1.6 IP(num_expr)

IP truncates the value of a real number at the decimal point and returns the integer portion. See Section 6.1.3, FP(num_expr).

Example 6-6 IP function

print ip(1234.56) 1234

6.1.7 MAX(num_expr, num_expr)

MAX(x,y) returns the larger of the two values x and y. See also "MIN function".

Example 6-7 MAX function

print max(5, 9) 9

6.1.8 MIN(num_expr1, num_expr2)

MIN(x,y) returns the lesser of the values x and y. See also "MAX function".

Example 6-8 MIN function

x = 43 y = 19 print min(x, y) 19

6.1.9 MOD(num_expr1, num_expr2)

MOD gives the remainder of one number divided by another.

Example 6-9 MOD function

print mod(36, 13) 10

6.1.10 REAL(num_expr)

REAL changes any numeric expression into a real or floating-point value and assigns the real value to the variable specified.

Example 6-10 REAL function

input 'Your age': age% let decimal_age = real(age%) print 'Your number is'; decimal_age end Your age? 31 Your number is 31

6.1.11 REMAINDER(num_expr1, num_expr2)

REMAINDER(x,y) returns the remainder when X is divided by Y. It differs subtly from MOD. MOD(-4,3) = 2 while REMAINDER(-4,3) = -1.

Example 6-11 REMAINDER function

print remainder(-4,3) -1

6.1.12 RND

or

RND(num_expr)

RND returns a random number greater than or equal to zero and less than one. If a numeric expression (num_expr) is given, RND returns a whole number between one and the numeric expression.

Example 6-12 RND function

print rnd .9409720199182629

6.1.13 ROUND(num_expr [, int_expr])

ROUND rounds a num_expr to the specified number of decimal places (int_expr). The default int_expr is 0.

Example 6-13 ROUND function

print round(21.83492, 2) 21.83

6.1.14 TRUNCATE(num_expr, int_expr)

This function truncates a real number to a given number of decimal places.

Example 6-14 TRUNCATE function

print truncate(123.45678, 2) print truncate(123.45678, 4) end 123.45 123.4567

6.2 Transcendental Functions

The following are transcendental functions that SheerPower performs:

ABS returns the absolute value of a specified numeric expression.

Example 6-15 ABS function

print abs(-5) 5

6.2.2 ACOS(num_expr)

The arccosine of X (ACOS(x)) returns the angle whose COS is x. The angle is returned in radians. ACOS has to be between -1 and +1 (inclusive).

Example 6-16 ACOS function

print acos(.75) .722734247813

6.2.3 ANGLE(num_expr, num_expr)

Given X and Y coordinates, the ANGLE function returns the angle from 0,0 in radians.

Example 6-17 ANGLE function

print angle(4,9) 1.152571997216

6.2.4 ASIN(num_expr)

The arcsine of X (ASIN(x)) returns the angle whose SIN is x. The angle is returned in radians. ASIN has to be between -1 and +1 (inclusive).

Example 6-18 ASIN function

print asin(.3) .304692654015

6.2.5 ATN(num_expr)

Arctangent (ATN) returns the angle, in radians, of a specified tangent.

Example 6-19 ATN function

print atn(33) 1.540502566876

6.2.6 COS(num_expr)

COS returns the cosine of an angle the user specifies in radians.

Example 6-20 COS function

print cos(64) .39185723043

6.2.7 COSH(num_expr)

COSH returns the hyperbolic cosine of a passed real number.

Example 6-21 COSH function

print cosh(31) 14524424832623.712890625

6.2.8 COT(num_expr)

Cotangent (COT(X)) is equivalent to 1/TAN(X).

Example 6-22 COT function

print cot(31) -2.2640027937804799

6.2.9 CSC(num_expr)

CSC(x) is the cosecant of X. It is shorthand for 1/SIN(x).

Example 6-23 CSC function

print csc(187) -1.0028370028157145

6.2.10 DEG(num_expr)

Given an angle in radians, the DEG function returns the number of degrees.

Example 6-24 DEG function

print deg(14) 802.140913183152502

6.2.11 EXP(num_expr)

EXP function returns the value of the mathematical constant, "e", raised to a specified power.

Example 6-25 EXP function

print exp(5) 148.413159102577

6.2.12 LOG(num_expr)

LOG returns the natural logarithm of a specified number.

Example 6-26 LOG function

print log(100) 4.605170186

6.2.13 LOG2(num_expr)

LOG2 returns a number's base 2 logarithm.

Example 6-27 LOG2 function

print log2(100) 6.643856189775

6.2.14 LOG10(num_expr)

LOG10 returns a number's common logarithm.

Example 6-28 LOG10 function

print log10(100) 2

6.2.15 PI

Returns the value 3.1415926535897932.

Example 6-29 PI function

print pi 3.1415926535897932

6.2.16 RAD(num_expr)

Given a measurement in degrees, the RAD function returns the number of radians.

Example 6-30 RAD function

print rad(85) 1.4835298641951801

6.2.17 SEC(num_expr)

SEC returns a secant of a given angle (1/COS(num_expr)). num_expr is a passed angle.

Example 6-31 SEC function

print sec(5) 3.5253200858189003

6.2.18 SGN(num_expr)

SGN returns the sign of a number. It returns a +1 if the expression is positive, a -1 if the expression is negative, and 0 if the expression is zero.

Example 6-32 SGN function

print sgn(-238) print sgn(238) print sgn(0) -1 1 0

6.2.19 SIN(num_expr)

SIN returns the sine of an angle specified in radians.

Example 6-33 SIN function

print sin(23) -.846220404

6.2.20 SINH(num_expr)

SINH(X) returns the hyperbolic sine X.

Example 6-34 SINH function

print sinh(23) 4872401723.124451637268

6.2.21 SQR(num_expr)

SQR returns the square root of a number.

Example 6-35 SQR function

print sqr(64) 8

6.2.22 TAN(num_expr)

TAN returns the tangent of an angle that is specified in radians.

Example 6-36 TAN function

print tan(0.2) .202710035509

6.2.23 TANH(num_expr)

TANH returns the hyperbolic tangent of the numeric expression given.

Example 6-37 TANH function

print tanh(0.5) .46211715726

6.3 Date and Time Functions

The following are date and time functions that SheerPower performs:

DATE returns today's date in YYDDD format. The 'DDD' is the number of days that have gone by so far this year.

Example 6-38 DATE function

print date 3117

6.3.2 DATE$[(int_expr1, [int_expr2])]

The DATE$ function returns the date in image format. int_expr1 is a given Julian day number, the default is today's date. int_expr2 indicates the desired output format for the date. The Julian day is the number of days since January 1, 1600.

Table 6-1 DATE$ function - integer values

Value (int_expr2)	Output Date Format
0	YYYYMMDD format
1	MMDDYYYY format
2	DDMMYYYY format
3	dd-Mon-yyyy format
4	Month dd, yyyy format

Example 6-39 DATE$ function

print date$ - gives 20010424 print date$(days(date$),1) - gives 04242001 print date$(days(date$),2) - gives 24042001 print date$(days(date$),3) - gives 24-Apr-2001 print date$(days(date$),4) - gives April 20, 2001

6.3.3 DAYS(str_expr [, int_num])

Given a date in CCYYMMDD or YYMMDD format, the DAYS function returns the number of days since January 1, 1600 (this date is day 1). This number is called the Julian day.

Example 6-40 DAYS function

print days('20000122') print days('990122') end 146119 145754

int_num indicates the desired input format for the date. The default input format is zero. If the century is not included, it assumes 1900 as the century.

Table 6-2 DAYS function - integer values

Value (int_num)	Input Date Format
0	CCYYMMDD or YYMMDD
1	MMDDCCYY or MMDDYY
2	DDMMCCYY or DDMMYY
3	DD-Mon-CCYY or DD-Mon-YY
4	Month DD, CCYY

Example 6-41 DAYS function - integer values

print days('20000103',0) print days('01032000',1) print days('03012000',2) print days('03-Jan-2000',3) print days('January 3, 2000',4) end 146100 146100 146100 146100 146100

6.3.4 DAY$[(int_expr)]

Given an integer expression specifying the number of days since January 1, 1600, DAY$ returns the day of the week. If no integer expression is given, DAY$ returns the day of the week for today's date. The day is returned as a string expression (Friday, Saturday, etc.).

Example 6-42 DAY$ function

print day$ Saturday

6.3.5 FULLTIME$[(float_expr, [int_var])]

Given the number of seconds since the SheerPower base date, the FULLTIME$ function returns the date and time in one of the formats given below.

float_expr is the number of seconds since the SheerPower base date. The default is the current date and time. January 1, 1600 00:00:00 is considered the second 0.

Table 6-3 FULLTIME$ function - integer values

Value (int_var)	Output Data Format
0	CCYYMDD HHMMSS
1	MMDDCCYY HHMMSS
2	DDMMCCYY HHMMSS
3	DD-Mon-CCYY HH:MM:SS
4	Month DD, CCYY HH:MM:SS

Example 6-43 FULLTIME$ function

print fulltime$ sec = seconds('20000121 115042') print fulltime$(sec, 0) print fulltime$(sec, 1) print fulltime$(sec, 2) print fulltime$(sec, 3) print fulltime$(sec, 4) end 20000208 232653 20000121 115042 01212000 115042 21012000 115042 21-Jan-2000 11:50:42 January 21, 2000 11:50:42

6.3.6 SECONDS(str_expr)

Given a full-time string in CCYYMMDD HHMMSS, YYMMDD HHMMSS, HHMMSS or HHMM format, the SECONDS function returns the number of seconds since the SheerPower base date (January 1, 1600 00:00:00).

The number of seconds is returned as a floating point number.

Example 6-44 SECONDS function

z = seconds('20000122 103050') z1 = seconds('990122 103050') z2 = seconds('103050') z3 = seconds('1030') print 'Seconds cymdhms ='; z print 'Seconds ymdhms ='; z1 print 'Seconds hms ='; z2 print 'Seconds hm ='; z3 end Seconds cymdhms = 12624633050 seconds ymdhms = 12593097050 seconds hms = 37850 seconds hm = 37800

6.3.7 TIME(int_expr)

The value returned by the TIME function depends on the value of int_expr.

If int_expr = 0, TIME returns the number of seconds since midnight.

If int_expr = 1, TIME returns the CPU time of the process in tenths of a second.

If int_expr = 2, TIME returns connect time of the current process in minutes.

Example 6-45 TIME function

print time(0) print time(1) print time(2) end 67004 1 0

6.3.8 TIME(5)

TIME(5) returns the number of seconds since SheerPower was invoked. This function can be used to time events to the nearest 100th/sec.

Example 6-46 TIME(5) function

print time(5) .03

6.3.9 TIME$

or

TIME$(num_expr)

If num_expr is NOT specified, TIME$ returns the current time of day in HH:MM:SS format.

num_expr is the number of seconds since midnight. The result is returned in HH:MM format.

Example 6-47 TIME$ function

print time$(1800) print time$(54178) print time$ end 00:30 15:02 11:33:27

6.3.10 Pivot Date

Many applications allow the end-user to enter a six-digit date. For a six-digit date, SheerPower 4GL needs to know if the YEAR is in the 19th century or the 20th century. For example:

161231

Is this 1916, December 31st or is this 2016, December 31st?

By default, SheerPower assumes that if a six-digit date is given, and the YEAR is less than 20, then this is the 20th century. In the example above,:

161231 --> December 31, 2016

The default PIVOT DATE is year 20.

The default pivot date can be changed by creating a logical:

SheerPower_Y2K_PIVOT

This can be done with the following small program:

Example 6-48 Pivot Date Logical

set system, logical 'SheerPower_Y2K_PIVOT': value '17'

You can add the following to the c:\sheerpower\sp4gl_YOURNAME.ini file:

[logicals] SheerPower_Y2K_PIVOT=17

Then the value will automatically be setup for all SheerPower applications. The logical is checked for only ONCE at sp4gl.exe STARTUP time.

The following are string manipulation functions that SheerPower performs:

The ASCII function returns the decimal ASCII value of a string's first character. It is returned as an integer. The Section 6.4.4 is the opposite of the ASCII function.

Example 6-49 ASCII function

print ascii('A') 65

6.4.2 CHANGE$(str_expr1, str_expr2, str_expr3)

CHANGE$ changes specified characters in str_expr1. str_expr1 is the source string. str_expr2 contains the target characters, and str_expr3 specifies the substitution characters. CHANGE$ returns the changed string.

CHANGE$ searches for the target characters within the source string and replaces these characters with the substitution characters. The substitution characters are mapped onto the target characters.

Example 6-50 CHANGE$ function

let a$ = 'bdbdbdbd' let b$ = 'b' let c$ = 'c' let changed$ = change$(a$, b$, c$) print a$ print changed$ end bdbdbdbd cdcdcdcd

6.4.3 CHARSET$[(str_expr)]

CHARSET$ returns the character set specified. The optional string expression can be used to specify the character set to return. The available character sets are:

Table 6-4 Available character sets for CHARSET$

	UCASE	all upper-case letters (A-Z)
	LCASE	all lower-case letters (a-z)
	CONTROL	all control characters (ASCII 0-31)
	ASCII	the ASCII character set, in order (0-255)

ASCII is the default character set for CHARSET$.

Example 6-51 CHARSET$ function

line input 'Enter your text': text$ // change upper-case to lower-case ct$ = change$(text$, & charset$('ucase'), & charset$('lcase')) print 'Lower-case version is:'; ct$ end Enter your text? TESTER Lower-case version is: tester

6.4.4 CHR$(int_expr1[, int_expr2])

CHR$ returns a string with the specified ASCII value (int_expr1) repeated the specified number of times (int_expr2). If no count is specified, a default count of one is used.

Example 6-52 CHR$ function

x = 65 print chr$(x) // prints A -- the 65th ASCII character end A

6.4.5 CONVERT$(int_expr1 [[, int_expr2], int_expr3])

Given an integer (int_expr1) and an optional length (int_expr2), which defaults to four, the CONVERT$ function returns a string mapping of the integer.

If the optional data type (int_expr3) is 17, the returned string will be a packed floating (PF).

The following data types are supported:

Table 6-5 CONVERT$ function - supported data types

Data Type	Conversion Result
1	Integer (2 or 4 byte)
7	COBOL comp-3 (C3 packed decimal)
17	Packed floating (PF)

Example 6-53 CONVERT$ function - supported data types

a$ = convert$(16961) print a$ end AB

6.4.6 CONVERT(str_expr)

Given a string containing a mapped integer, the CONVERT function returns the integer value.

Example 6-54 CONVERT function

a$ = 'AB' b = convert(a$) print b end 16961

The CONVERT and CONVERT$ functions can be used in situations such as building segmented keys consisting of multiple data types.

CPAD$ returns a new string, padded on the left and on the right with pad characters. text_str is the string to be centered, size is the size of the new string. The default pad character is a space.

Example 6-55 CPAD$ function

print cpad$('123', 9, '0') end 000123000

6.4.8 EDIT$(str_expr,int_expr)

EDIT$ performs one or more editing operations on the supplied string argument, depending on the value of the integer expression. The integer expression is one of the integers below, or a sum of integers below for the desired edit functions:

Table 6-6 EDIT$ function - operation values

Value	Edit Operation
1	Trim parity bits.
2	Discard all spaces and tabs.
4	Discard characters: CR, LF, FF, ESC, RUBOUT and NULL.
8	Discard leading spaces and tabs.
16	Reduce spaces and tabs to One space.
32	Convert lower case to upper case.
64	Convert "[" to "(" and "]" to ")".
128	Discard trailing spaces and tabs.
256	Do not alter characters inside quotes.

Example 6-56 EDIT$ function

print edit$('hi there, how are you today?' , 32) HI THERE, HOW ARE YOU TODAY?

6.4.9 ELEMENTS(str_expr1 [, str_expr2])

The ELEMENTS function returns the number of elements in a string expression that contains a list of elements. str_expr1 is the string containing the list of elements. str_expr2 is the separator. A comma is the default separator.

• Leading and trailing spaces are removed from the text.
• Quoted data is treated as one element.

A given element is considered quoted only if the first non-blank character of the element is a single or double quote mark.

Example 6-57 ELEMENTS function

alphabet$ = 'a;b;c;d;e;f;g;h;i;j;k;l;m;n;o;p;q;r;s;t;u;v;w;x;y;z' print elements(alphabet$, ';') end 26

6.4.10 ELEMENT$(str_expr1, num_expr [, str_expr2])

ELEMENT$ returns the element from str_expr1 which is specified by the num_expr. str_expr1 contains a set of elements with separators between them. The default separator is a comma:

Example 6-58 ELEMENT$ function

let a$ = element$('ADD,DEL,EXIT',2) print a$ end DEL

A separator other than the comma can be specified with str_expr2.

Example 6-59 ELEMENT$ function - separators

let sentence$ = 'This is a test.' let a$ = element$(sentence$,2,' ') print a$ end is

More than one separator in a row returns a null for the corresponding element.

Example 6-60 ELEMENT$ function - separators

let sentence$ = 'This,, is, a, test' print element$(sentence$, 2) end

6.4.11 ENCODE$(num_expr, num_int)

The ENCODE$ function returns a string containing a number converted to the base specified. num_expr is the value to convert. num_int is the base to convert. For instance, '2' indicates binary, etc. See also Section 6.9.1, DECODE(str_expr, int_expr)

Example 6-61 ENCODE$ function

do input 'Enter a number to convert to hex': decnum if decnum = 0 or _exit then exit do print 'Hex for'; decnum;' is '; encode$(decnum,16) loop end Enter a number to convert to hex? 34.56 Hex for 34.56 is 22 Enter a number to convert to hex? 255 Hex for 255 is FF

6.4.12 FORMAT$(expr, str_expr)

Given an expression and a format, FORMAT$ returns the result of the expression in the format indicated.

The '@' format character causes the character not to be translated by the formatter. The '<' and '>' are treated like an '@' character. You can justify a character string, but avoid zero suppression and zero insertion.

The FORMAT$ function takes an expression of any data type for the data to format (the first argument), including string expressions.

Example 6-62 FORMAT$ function

z$ = format$('1234567', '###~-####') print 'Phone number: '; z$ end Phone number: 123-4567

The FORMAT$ function returns all asterisks "*" in the case of overflow.

Example 6-63 FORMAT$ function

z$ = format$(12.23,'#.##') print z$ end ****

FORMAT$() returns the same string data as given by the following:

PRINT USING str_expr: expr

The FORMAT$ function supports the DATE format and date arguments. Given a date in YYMMDD or CCYYMMDD format, FORMAT$ returns the date in the date format requested.

FORMAT$(z$, '{DATE [argument]}?')

The ? can be replaced with a mask. If no date argument is provided, the default is MDCY.

Example 6-64 DATE format with FORMAT$

z1$ = format$('990122', '{date mdcy}?') z2$ = format$('990122', '{date mdcy}##/##/####') z3$ = format$('20000122', '{date mdcy}?') z4$ = format$('20000122', '{date mdcy}##/##/####') print z1$, z2$ print z3$, z4$ end 01221999 01/22/1999 01222000 01/22/2000

Table 6-7 FORMAT$ function - date arguments

DATE Argument	YYMMDD Input	Result	CCYYMMDD Input	Result
none	990207	02072000	20000207	02072000
YMD	990207	990207	20000207	990207
CYMD	990207	20000207	20000207	20000207
MDY	990207	022199	20000207	022199
MDCY	990207	02072000	20000207	02072000
DMY	990207	070299	20000207	070299
DMCY	990207	07022000	20000207	07022000
DMONY	990207	07-Feb-99	20000207	07-Feb-99
DMONCY	990207	07-Feb-2000	20000207	07-Feb-2000
MONTHDY	990207	February 7, 99	20000207	February 7, 99
MONTHDCY	990207	February 7, 2000	20000207	February 7, 2000

The FORMAT$ function supports character rotation. The ROTATE option rotates the last nn characters of a string to the first position in the string.

FORMAT$(z$, '{ROTATE n}?')

The ? can be replaced with a mask.

The GETSYMBOL$ function is used to return script variables and symbols. These can be the results of an HTML form submission, CGI environment variables, SheerPower symbols, DNS symbols, operating system symbols, or any variable you have defined as a symbol.

The GETSYMBOL$ function has an optional parameter that allows you to not trim the leading and trailing spaces of a symbol returned. The default parameter is set to TRUE. "True" is implied and means that the leading and trailing spaces will be trimmed. The FALSE parameter can be used if you do not want the leading and trailing spaces trimmed from the symbol retrieved.

Example 6-65 GETSYMBOL$ function - SheerPower Symbol & Trimming Option

set system, symbol 'test': value ' hi there' print '<';getsymbol$('sp:test');'>' print '<';getsymbol$('sp:test', false);'>' print '<';getsymbol$('sp:test', true);'>' <hi there> < hi there> <hi there>

Below are a few more examples of GETSYMBOL$:

Example 6-66 GETSYMBOL$ function - HTML form submission

// print the contents of the symbol "city" from a HTML form submit. print getsymbol$('city')

Example 6-67 GETSYMBOL$ function - CGI Environment Symbol

// print the contents of the environment symbol REMOTE_ADDR print getsymbol$('env:REMOTE_ADDR')

Example 6-68 GETSYMBOL$ function - Operating System Symbol

// print the contents of the operating system symbol PATH print getsymbol$('os:PATH') // and list the contents of the TEMP directory print getsymbol$('os:TEMP') C:\PROGRA~1\Java\JRE16~2.0_0\bin;C:\PROGRA~1\Java\JRE16~2.0_0\bin;C:\WINDOWS\sys tem32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\PROGRA~1\ABSOLU~1;C:\Program Files\ QuickTime\QTSystem\;C:\Program Files\IDM Computer Solutions\UltraEdit\;C:\Progra m Files\IDM Computer Solutions\UltraCompare;. C:\DOCUME~1\User\LOCALS~1\Temp

Below is a list of symbol prefixes supported:

Table 6-8 Supported Symbol Prefixes

Symbol Prefix	Description
env:	CGI environment variables (see Section 19.3.8, Summary of CGI Environment Variables)
os:	Operating system symbols. If the symbol begins with a \ then it is a registry symbol.
sp:	SheerPower symbols (see Section 11.14.15, SET SYSTEM, SYMBOL: VALUE )
dns:	DNS symbols (see Section 11.14.14, Performing DNS Lookups with ASK SYSTEM, SYMBOL )

The HASH$ function changes the plain text in str_expr1 into a hashed eight-byte string value. It can be used to develop one-way hashed passwords. The optional text in str_expr2 and optional int_expr can be used to further make the hashed value unique.

Example 6-69 HASH$ function

password$ = hash$('TRUTH') input 'Password': pwd$ if hash$(pwd$) = password$ then print 'That was the correct password.' else print 'That was not the correct password.' end if end password? MONEY That was not the correct password.