Creating a Procedure

In this section:

Including Comments in a Procedure
Sending a Message to the User
Controlling User Access to Data
Creating a Startup Procedure

Reference:

Rules for Creating Procedures

You can use the FOCUS integrated text editor, TED, or invoke your system editor from FOCUS with the IEDIT command to create procedures that contain Dialogue Manager functionality. IEDIT is especially useful with variable length files or those whose record lengths are greater than 80 characters.

TED and IEDIT have two valuable features for creating and editing procedures:

If you issue the TED command, or invoke your system editor using the IEDIT command without specifying a procedure name, the last executed procedure is automatically selected. This is convenient when developing and testing new procedures.
Test the execution of the procedure by typing RUN on the command line in TED or in a system editor accessed with the IEDIT command. RUN automatically saves the procedure and executes it. If there is an error in your procedure, type TED or IEDIT to bring you back to the editor. It places you directly on the line in which the error was detected.

For details, see Editing Files With TED and Invoking Your System Editor With IEDIT in the Overview and Operating Environments manual.

These options complement the FILE and SAVE options that are common to other editors.

In addition to Dialogue Manager commands and variables that directly affect an application's flow of control, you can use commands to:

Add comments to a procedure. See Including Comments in a Procedure.
Send messages to the terminal. See Sending a Message to the User.
Control user access to data. See Controlling User Access to Data.

You can also create a profile procedure that defines startup conditions and can include Dialogue Manager commands. See Creating a Startup Procedure.

Reference: Rules for Creating Procedures

Follow these general rules when creating procedures:

Dialogue Manager commands must begin in the first position of the line.
At least one space must be inserted between the Dialogue Manager command and other text.
If a Dialogue Manager command exceeds one line, the following line must begin with a hyphen (-). The continuation line must have a space between the hyphen and the rest of the line.
Procedure names cannot contain special characters.

Including Comments in a Procedure

How to:

Add a Comment in a Procedure

Include comments in a procedure for the benefit of others who may use it. It is particularly recommended that you use comments in a procedure heading to supply the date, the version, and other relevant information. A hyphen and an asterisk (-*) mark the beginning of a comment.

Comments do not appear on the terminal nor do they trigger processing. They are visible only when viewing the contents of the procedure through the editor and are strictly for the benefit of the developer. However, you can view comments on the terminal by using the &ECHO variable. For details, see Debugging a Procedure.

Syntax: How to Add a Comment in a Procedure

Begin the comment line with the command:
```
-*
```
Type the comment text after the command, optionally with a space before the text.

You can place a comment at the beginning or end of a procedure or in between commands. A comment cannot be on the same line as a command.

The following entry is valid:

.
.
.
-*Version 2 06/10/00
-RUN

The following is invalid:

-RUN -*Version 2 06/10/00

Example: Placing a Comment in a Procedure

The following example places a comment at the beginning of a procedure.

-* Version 1  08/26/02  HRINFO  Procedure
TABLE FILE CENTHR
   .
   .
   .

Sending a Message to the User

How to:

Send a Message to the User

You can use the -TYPE command to send a message to the terminal while a procedure is processing. Typically, the message serves the following purposes:

Explains the purpose of the procedure.
Displays the results of a procedure or calculation during testing of a procedure.
Presents other useful information.
Indicates what type of information to supply in response to a prompt.

Syntax: How to Send a Message to the User

-TYPE sends the message to the terminal as soon as it is encountered in the processing of a procedure. The syntax is

-TYPE[+|0|1] text

-label TYPE text

where:

text

Is the message to be sent. The message is sent to the screen, followed by a line feed. It remains on screen until scrolled off or replaced by a new screen.

If you include quotation marks around the text, they are displayed as part of the message. (This differs from the use of TYPE in MODIFY, where quotation marks are used as delimiters and must enclose informative text.)

-label

Is the target of a -GOTO or -IF.

+|0|1

Are optional entries that pass printer control characters to the output device. They are particularly useful for character printers. Options + and 1 do not work on IBM 3270-type terminals.

+ suppresses the line feed following the printing of text.

0 forces a line feed before the message text is displayed.

1 forces a page eject before the message text is printed.

If supplied, these values must follow -TYPE without a space.

Example: Sending a Message

The following example illustrates the use of -TYPE to inform a user about the content of a report:

-* Version 1  06/26/00  SLRPT  Procedure
-* Component of Retail Sales Reporting Module
-TYPE This report calculates percentage of returns.
TABLE FILE SALES
 .
 .
 .
END

Controlling User Access to Data

How to:

Set a Password in a Procedure

You can issue and control passwords with the -PASS command. This is especially useful for specifying a password for a particular file or set of files that a given user can read from or write to. Passwords have detailed sets of functions associated with them through the DBA facility.

The procedure that sets passwords can be encrypted so that it and the passwords that it sets cannot be typed and made known.

A variable can also be associated with -PASS so that you can prompt for and assign a password value. You can also check the value of the password and skip or execute a portion of the procedure depending on the value.

Syntax: How to Set a Password in a Procedure

-PASS password

where:

password: Is a password or a variable containing a password.

Since -PASS is a Dialogue Manager command, it executes immediately and is not sent to the FOCSTACK. This means that the user need not issue the password with the SET command.

Creating a Startup Procedure

You can establish startup conditions in a profile that executes its content immediately upon entry into FOCUS. Using this procedure you can:

Establish standard conditions that apply throughout the subsequent working session. For example, you can predefine environment parameters or automatically compute variables and make them available for later use.
Provide a menu of subsequent user options.
Control use of an application.

You can create a profile using any text editor or the FOCUS editor TED. The file is a procedure (FOCEXEC) named PROFILE.

Note: It is possible to use an alternate procedure as a profile or not to execute a profile at all. For more information, see the Overview and Operating Environments manual.

Example: Creating a Startup Profile

The following example creates a startup profile):

USE
SALES
EMPLOYEE
END
DYNAM ALLOC DD MYSAV DA USER1.SAVE.TEMP SHR REU
DEFINE FILE SALES
RATIO/D5.2 = (RETURNS/UNIT_SOLD);
END 
-TYPE FOCUS SESSION ON &DATE MDYY &TOD

LET WORKREPORT=TABLE FILE EMPLOYEE
SET LINES=57, PAPER=66, PAGE=OFF
OFFLINE

Upon entering FOCUS, the profile is executed and a message, introduced by the -TYPE command, displays the current date and time.