Chapter 12

From Br Wiki
Jump to: navigation, search

The information and exercises in this chapter will introduce you to the ground rules about using procedures. When you finish you will be able to:

  • Name 3 ways to start a procedure file.
  • Name 2 ways to create procedure file.
  • Use a few special commands used only with procedures.
  • PROC and SUBPROC commands.
  • Edit procedure files.

12.1 Procedure command

A procedure is a file that (usually) contains system commands that are executed as if they were typed at the keyboard by the operator. A procedure can execute a series of commands without any intervention by the operator. To give a simple but very useful example, the procedure file START could contain the following two lines:

LOAD C:\BR\MAINMENU
RUN

After you have entered Business Rules!, just type PROC START to execute the program MAINMENU.BR on drive C: in the BR directory. (If you don’t have the program MAINMENU in your directory, it won’t be able to run it, of course. But a similar procedure could be made to run any existing program). PROC is a system command that opens a procedure file and starts executing each line in the file as if the line had been typed at the keyboard by the operator.

A procedure file is a display file made up of ASCII text characters. This means it can be created or modified by any of the standard means for processing files of text characters (for example, text editors like the DOS program EDIT, VI, or Notepad, and other methods to be discussed later in this chapter).

Quick Quiz 12.1

1. A procedure file:
a) Is a DISPLAY file.
b) Is an INTERNAL file.
c) Requires the operator to do something before each command is executed.

2. The purpose of the PROC command is:
a) To create a procedure file.
b) To modify a procedure file.
c) To begin execution of a procedure.

Answers:
1-a; 2-c.

12.2 Why use procedures?

The major reason for using procedures is to make life easier for the operator. Sometimes operators misspell the names of your programs. Sometimes operators are supposed to run four programs in a row to accomplish a certain task, such as closing out the end of the month for some accounting application. You could use a procedure to prevent the bad things that could happen if an operator forgot to run one of the four programs. In short, procedures help the operator because they minimize typing errors and reduce the number of individual steps that the operator has to remember.

Some of the reasons for using procedures may remind you of the reasons for using menus because both menus and procedures are used to help the operator. In fact, procedures and menus work quite well together. Later in this chapter, you will learn how to start a procedure from a menu.

Let’s consider a more detailed example of a procedure. Suppose that the end of a month requires running two report programs, a transfer program, and a program to clear the files for the new month. If you are not familiar with some of this accounting jargon, just think of it as four programs that have to be run in a fixed order. In this example, these four programs have the following names and descriptions:

1. TRANSLST.BR Prints a detailed list of all transactions for the month.

2. SUMRYLST.BR Prints a summary of transactions for the month.

3. GLTRANSF.BR Transfers information to the General Ledger data files.

4. NEWMONTH.BR Clears data for this month from files to start fresh for next month.

Suppose that these four programs absolutely must be run in this order (Can you imagine the problems if the fourth program were run before anyone noticed that one of the first three was missing?). Finally, let’s also suppose that the transfer program in step 3 is also used for end-of-year transfers; to select monthly transfers, the operator must select option “1” from a menu that does not use full-screen processing. The menu for this program might look like this:

Please select one of the following:
1 -- End-of-month transfer
2 -- End-of-year transfer

Except for the option in program 3 (which we will handle later in this chapter), you could code the following procedure file (called EOM) to handle this four-step process:

LOAD TRANSLST
RUN
LOAD SUMRYLST
RUN
LOAD GLTRANSF
RUN
LOAD NEWMONTH
RUN

Running this procedure would assure that these four programs would always be run in the proper order. To begin execution of this procedure, the user would type PROC EOM.

The first command would load the TRANSLST program. The next command would run this program. After TRANSLST has finished running, the system again looks for the next command in the procedure. This process continues until the end of the procedure file is reached. Because this procedure file was started from the keyboard, the system returns to the keyboard in READY mode after the procedure has finished.

To make procedures easier to read, comments may be added using the exclamation mark (!) either at the end of a line or on a separate line. Another rule is that only one command can be coded on each line in a procedure. Also, notice that lines in a procedure file do not have line numbers. After adding comments to the above procedure, the EOM file would look like this.

! End-of-month procedure
! John Q. Programmer -- 09/19/05
LOAD TRANSLST    	! print detailed transaction list
RUN
LOAD SUMRYLST    	! print transaction summary list
RUN
LOAD GLTRANSF    	! transfer to G/L -- must take option 1
RUN
LOAD NEWMONTH  	! clear files for new month
RUN

Let’s review how this procedure helps the operator. First, the procedure is only set up once, and then used each month; so, after the first month, there is less typing. Second, once the procedure is correct, it will prevent errors in future months. Before we discuss the third point, let’s backup and review something we said in the beginning.

Remember that earlier we made a distinction between the job of the programmer and the job of the operator.

The programmer is responsible for the development or programming of the system, and the operator is responsible for on-going operation of the system. Procedures are usually set up by programmers when they are developing the system. So, in our discussion of whether procedures save work for the operator, the third point is that the operator is usually not the one who types in all these steps -- just as the operator does not usually type in the programs. Thus, a procedure is another programming tool available to help automate the processing of data.

Quick Quiz 12.2

1. Using a procedure is less work for:

a) The operator.
b) The programmer.
c) The computer.

2. Procedures are usually set up by:

a) The operator.
b) The programmer.
c) The computer.

3. The advantages of using a procedure include:

a) Helping the operator by reducing typing errors.
b) Helping the operator by reducing the number of individual steps that the operator must remember to do.
c) Helping the operator by correctly arranging sequences of things that must be done in a certain order.
d) All of the above.

4. Identify the statement below which is not one of the rules for coding procedures.

a) Two commands can not appear on the same line.
b) Lines must begin with a line number.
c) Comments may be coded on the end of a command line.
d) Comments may be coded as separate lines without any command on that line.

Answers 12.2

12.3 How to Create a procedure

A procedure file is a Business Rules! DISPLAY file, that means a standard DOS (or Unix/Linux) text file, also called an ASCII text file. It can be created or modified using any standard means of creating or editing a text file. That probably sounds easy if you’ve done all this before, and it probably sounds vague, confusing and mysterious if your are learning all this for the first time. Let’s go through some of this step-by-step. The remainder of this section will briefly summarize two ways to create text files for your procedures, and then go through the first one in detail.

  1. From outside Business Rules!, use a text editor such as EDIT, EDIPAD or Notepad.
  2. From inside Business Rules!, write a Business Rules! program to OPEN a DISPLAY file and PRINT lines of text. This is for advanced programming techniques.

Of these two ways to create a procedure file, the first one is recommended for beginners. It’s simple to create and can be accessed from any BR program.

Simply open your text editor (Notepad, for example) and type in the commands that you would like the procedure to run. We can easily create the procedure mentioned in the previous section by copying and pasting it into your text editor.

! End-of-month procedure
! John Q. Programmer -- 09/19/05
LOAD TRANSLST    	! print detailed transaction list
RUN
LOAD SUMRYLST    	! print transaction summary list
RUN
LOAD GLTRANSF    	! transfer to G/L -- must take option 1
RUN
LOAD NEWMONTH  	! clear files for new month
RUN

Save this under the name “eom”. The programs mentioned in it are available with the supplemental programs provided with this tutorial (soon available at ftp.brulescorp.com).

Syntax for a PROC is as follows:

PROC NAME.EXT

(The extension part is not necessary if the text file name doesn’t have one, of course)

So to access and run “eom” from BR, simply type:

PROC EOM.TXT (Your extension may be different according to the text editor used)

NOTE: Following PROC, you must type the complete name of the saved file, including any file extensions. Windows will hide file extensions if your default is set up to do so, but be sure to include them here. (ie. PROC EOM.TXT or PROC EOM.DOC).

The procedure will run all four programs in sequence to close out the end of the month (or year).

If you want to edit your procedure, simply open the text file, make your changes and save them.

Quick Quiz 12.3

1. True or False: A procedure can be created from within or from outside Business Rules.

2. True or False: Only the first four letters of the file name can be used with the PROC command to run a procedure.

Answers 12.3

12.4 How to start a procedure

The SUBPROC command runs one procedure from within another procedure. It performs the same function for a procedure file as a GOSUB statement does for a program. You already know how to enter and edit procedures; this section will tell you four ways to start a procedure. Before explaining these four, let’s look at a quick list of them using the EOM procedure file.

1. PROC EOM

2. SUBPROC EOM

3. 00950 CHAIN “proc=EOM”

4. C:\BR PROC EOM (from windows)

1. The PROC command is the most common method of starting a procedure. The PROC command opens the procedure file named in the PROC command, and then begins execution with the first line. The file name information can include a full pathname. The PROC command does not clear memory (unlike the CLEAR command). Also, it will close any other procedure files in the stack, the procedure file that executed the current program (unlike the SUBBPROC command).

2. The SUBPROC command allows you to run a second procedure from within the first procedure. The procedure file started by the SUBPROC command is called a nested procedure, and procedures may be nested up to 9 levels. The flow of control across nested SUBPROCs in procedures is much like the flow of control across nested GOSUBs in a program.

Here is another way to look at the difference between PROC and SUBPROC. To initiate another procedure from within a procedure, there are 2 options: either the next procedure cancels the current procedure, or the next procedure allows the continuing of the current procedure after it is finished. The SUBPROC command is used for this second case. It lets you exit the current procedure temporarily to run another procedure. When the second procedure is done, the system returns to the first procedure and starts again with the line after the SUBPROC command.

3. A procedure can also be started from a program with the CHAIN statement. This is a handy way to start a procedure from a menu. Suppose that there was a menu option for:

9. Run End-of-Month Closing Procedure

When someone selects option 9 (EOM procedure), the program should branch to a statement like the following:

01090 CHAIN “proc=EOM”

The CHAIN statement ends the program. Like the PROC command, it does not clear memory; it closes any active procedure files, opens the EOM procedure file, and begins executing the first line of that procedure. It is also possible to use the CHAIN statement to start the next procedure as a sub-procedure with a statement like the following:

01090 CHAIN “subproc=EOM”

The only difference in these two CHAIN statements is that “subproc=” will not close currently active procedure files, but “proc=” will close them.

4. Finally, another way to initiate a procedure is by entering Business Rules! using the BR command from your operating system (or from executable files or batch files from your operating system). Suppose your system had a Business Rules! procedure file named MENU to start your application package and present the first system menu.

One way to use this would be to tell the operator to type PROC MENU as the first command after entering Business Rules!. Alternatively, many systems are setup so that they automatically run a specified procedure every time they are started up. If you have a Windows operating system, an alternative way to get the same result is to make a shortcut to Business Rules and specify the path and PROC MENU as the target. You could also put PROC MENU in the BRConfig.sys file so that BR always opens directly to the Menu. This is how most operators will automatically access your BR programs upon startup.

If you have a Unix or Linux operating system, the equivalent command (entered after the “$” prompt) would be: BR “PROC MENU”

Either of these two startup commands will first start Business Rules!, and then start the Business Rules! procedure file called MENU automatically.

How to stop a procedure

To interrupt a procedure from the keyboard, hit CTRL-A to enter ATTN mode. When ATTN appears in the Status Line, you may enter any command, including the following two forms of the CLEAR command.

CLEAR PROC - ends the current program (if any), closes all active procedure files, but leaves memory as it is. CLEAR PROC is the most commonly used method of ending a procedure because it leaves memory unchanged, which is useful for debugging. Remember that interruptions from the keyboard are ignored during INDEX and SORT commands.

CLEAR ALL - ends the current program (if any), closes all active procedure files, and also clears memory.

One other way of stopping a procedure file is to execute another PROC command, which will close all previous procedure files, either from the keyboard in ATTN mode or from an active procedure file.

Quick Quiz 12.4

Each of the 12 items below (1-12), do two things. First, tell whether it is a command or a statement (if it is a statement, it should not produce a syntax error if it is typed in with a line number in front of it exactly as it appears below).

Second, identify what result (a-f) each of the 12 commands or statements will have when it is typed in from the keyboard when Business Rules! is in ATTN mode, a procedure is active, and a program is running. The six possible results are:

A. Stop the program, but the procedure is still active.
B. Stop the procedure, but the program is still in memory.
C. Stop the procedure, and erase the current program from memory.
D. No change on the program or procedure.
E. Error code 2108 -- Program is active
F. Error code 1001 -- Illegal use of reserved word

1. CLEAR PROC
2. END
3. CLEAR ALL
4. PROC EOM ! run 4 programs
5. CHAIN “MENU.BR”
6. STOP
7. PRINT ERR
8. SYSTEM
9. CHAIN “subproc=EOM”
10. CHAIN “proc=EOM”
11. SUBPROC EOM
12. REPLACE

Answers 12.4

12.5 System commands used only in procedures

This section will introduce four new commands. These commands are used only with procedures.

Question: How can I send a message to the operator and stop the procedure until the operator says things are ready to go?

Answer: Funny that you should ask, I was just going to tell you about the ALERT command.

To send a message to the operator, and stop a procedure until the operator says it’s time to go ahead, use the system command ALERT in the procedure file. The ALERT command stops execution of procedure so that the operator may change paper in the printer, insert a special CD, etc. For example, the procedure to print payroll checks might include the following ALERT statement:

ALERT Put payroll checks in printer, then type GO

When Business Rules! encounters an ALERT command in a procedure, it suspends the procedure and beeps. The word ALERT appears on the bottom line along with the optional message (although the message is optional, a good programmer would almost always want to include a message).

How does the operator get the system started again after stopping for an ALERT command? The system waits until the operator types a command. Typing GO will continue with the next step in the procedure. Typing CLEAR PROC allows you to terminate the current procedure.

Add the following ALERT to your EOM procedure where appropriate, then run it:

ALERT Confirm ready to clear all files, type GO to continue or CL PROC to stop.

The screen should look like this:

12.1.jpg

Then type GO to continue.

Question: When there is an error in the procedure, does it always have to stop the procedure and beep?

Answer: I am glad you asked that question, I was just going to tell you about the PROCERR command.

The PROCERR command tells Business Rules! how to respond when it finds an error in an active procedure. There are two choices: PROCERR STOP and PROCERR RETURN. When PROCERR STOP is in effect, the system will stop when an error occurs in a procedure. PROCERR STOP is assumed when the procedure is started. When PROCERR RETURN is in effect, the system will return to the next command when an error occurs. In short, with PROCERR RETURN, you never hear about the errors and your procedure just goes on to the next statement.

The FREE command used in a procedure provides a very common example of the use of both versions of the PROCERR command. Remember that the FREE command erases or deletes an entire file from the system. Usually (except on multi-user systems), you do not want the computer to stop if there is an error on a FREE command. The error usually means that the file is not there, which is exactly what the FREE command wanted in the first place. If the file is already gone, it is safe for the procedure to go on to its next step. To avoid this unwanted system halt, free the HISTORY.DAT file using the following common three-line sequence at the beginning of your procedure:

PROCERR RETURN
FREE HISTORY.DAT
PROCERR STOP

In the above example, PROCERR RETURN will temporarily prevent the system from stopping your procedures with error messages. The FREE command will try to free the file. If FREE succeeds, the file is gone. No error messages occur when commands succeed. If FREE fails, it failed because the file was already gone. The error will be registered only by changing the value of the system variable ERR (we will discuss this in more detail more in the next section). Because PROCERR RETURN is in effect when FREE fails, the system does not stop but goes to the next command. In this case, that’s good; the file is gone, and that’s what we wanted. For the rest of the procedure, it’s probably bad. You probably do want to know about errors in the next part of the procedure. Thus, it is important to instruct the system to report any further errors. Ending this section of the procedure by coding the command PROCERR STOP will restore the usual mode of having the system stop when an error occurs. Now normal error processing (with beeps and halts) is restored for the next commands in the procedure.

Question: How can I skip around a block of commands in a procedure that I don’t always want to execute?

Answer: I was just going to tell you about the SKIP command.

The SKIP command is used for branching in a procedure. SKIP causes lines in the procedure file to be passed over. Take a minute to look at the syntax below. The number following SKIP is the number of lines to be passed over. Remember that ERR is the system variable which contains the most recent error code.

LOAD PROG1
RUN
SKIP 4 IF ERR=0
ALERT  Insert HISTORY CD in Drive D: -- type GO
LOAD PROG2
RUN
SKIP 2
LOAD PROG3
RUN

The example above will load and run PROG1. If there is any error in PROG1, it will load and run PROG2. If there is no error in PROG1, it will load and run PROG3. Now let’s take a closer look at how SKIP statements are used to accomplish this.

The first SKIP statement is a conditional skip. Earlier, we discussed the three other statements used for conditional branching: the IF statement, ON GOTO statement, and ON GOSUB statement. The main characteristic of conditional branching is that sometimes it skips, and sometimes it doesn’t. Whether it skips or not depends on the tested condition--in this case, the condition is whether ERR is equal to zero. Let’s look at both possibilities. First, assume that there is no error. The condition in our test (ERR=0) will be true. When the condition is true, the SKIP will occur and the next 4 lines will be skipped. The next command executed will be LOAD PROG3. The RUN command will run PROG3, and then the procedure will end.

In the second case, when there is an error in PROG1, the condition in the test (ERR=0) will be false. When the condition is false, the SKIP does not occur. The line immediately following (the ALERT) is executed next. PROG2 will be loaded and run. Then the SKIP 2 command is encountered. Because there is no keyword “IF” and no condition in this line, this command is an unconditional branch. The GOTO statement is another example of unconditional branching.

The main characteristic of unconditional branching is that it always skips, there is never any alternative. The SKIP 2 command causes the loading and running of PROG3 to be skipped. Then the procedure will end. In fact, SKIP 999 or any number greater than 2 would also cause the procedure to end.

Let’s consider a few minor changes in the above procedure.

LOAD PROG1
RUN
SKIP NOHISTORY IF ERR
ALERT  Insert HISTORY CD in Drive D: -- type GO
LOAD PROG2
RUN
:NOHISTORY
SKIP DONE
LOAD PROG3
RUN
:DONE

In the two SKIP commands above, labels have been used instead of numbers to indicate where the procedure should skip to. The main advantage of using labels instead of numbers is that the SKIP commands will not have to be changed when lines are added to or deleted from the procedure. For instance, if numbers were used and an ALERT command were to be added before the LOAD PROG3 command, the SKIP command preceding the LOAD command would have to be changed to a SKIP 3 instead of leaving it as SKIP 2.

Changing the numbers in SKIP commands is not a hard thing to do, but it is one more detail to keep track of and one more thing that can go wrong. Procedures will work just fine either way. It’s a matter of style, so pick the method that seems to make the most sense to you (or the method that your boss tells you to use), then stick with it.

Notice a few more things about our changed procedure. Labels have been added and appear on separate lines. A line with a label must begin with a colon (:). Notice that this is different from the way colons are used with labels in statements in a program. Another rule is that nothing else may be on the line with the label. Finally, notice also that our test condition has been shortened from “IF ERR=0” to just “IF ERR”. These two forms produce the same results.

Question: Some of the programs in my procedure require data from the keyboard. Is there a way to have this data read in from the procedure?

Answer: I’m glad you asked that question. I was just going to tell you about the RUN PROC command.

The RUN command can include the optional keyword PROC. After a program has been loaded, the RUN PROC command will modify the program so that any INPUT, LINPUT or RINPUT statement expecting input from the keyboard will instead take its data from the next line(s) in the procedure file. No program changes are needed. Notice that RUN PROC cannot be used with INPUT FIELDS or RINPUT FIELDS.

The RUN PROC command allows us to finish up one last detail from the EOM procedure that we wrote at the beginning of this chapter. Take a moment to look back at that example. Notice that we said the GLTRANSF program was supposed to be run with option 1 to select monthly transfers and we even presented an example menu. Also, notice that the example states there is no full-screen processing; this means that RUN PROC will work since no INPUT FIELDS or RINPUT FIELDS statements are used. The changes to file EOM are given below to force the third program to use the first menu option. Try to make these changes yourself before you look at this listing. The changed version of EOM looks like this.

!  End-of-month procedure
!  John Q. Programmer -- 09/19/05
!
LOAD TRANSLST    	! print detailed transaction list
RUN
LOAD SUMRYLST   	! print transaction summary list
RUN
LOAD GLTRANSF    	! transfer to G/L -- must take option 1
RUN PROC              	! use INPUT from PROC given on line below
1
LOAD NEWMONTH 	! clear files for new month
RUN

After loading GLTRANSF, the RUN command is changed to a RUN PROC so that the first statement requiring keyboard input will take its data from the next line in the procedure file EOM. A line was added to EOM containing the data that would have been typed in at the keyboard; in this case, that line contains only the digit “1”. When GLTRANSF is finished, the system goes back to the procedure file and begins executing the next command.

Problems can occur when using RUN PROC if there are too many or too few lines of data in the procedure file. If GLTRANSF were expecting two lines of input in the EOM procedure above, and only one is provided, it would take the next line of the procedure file (the LOAD NEWMONTH command) and try to use it for input. If numeric data is required, a conversion error will occur. If you suspect this type of error has occurred, type CLEAR PROC to end the procedure before things get worse. If the procedure continues, it would execute the RUN command (the one after LOAD NEWMONTH) next. This would execute the program currently in memory, which would still be GLTRANSF (since the LOAD NEWMONTH command was used for data and caused the conversion error when GLTRNASF was run the first time). Around this time, the operator would probably be thoroughly confused; they would now be seeing the menu from GLTRANSF which they have never had to respond to before because the response has always been included in the procedure file. So, typing CLEAR PROC at the first error would save them from all this additional confusion.

Quick Quiz 12.5

1. What command can be used to keep a program from stopping and beeping when an error occurs?
a.) PROCERR RETURN
b.) ALERT
c.) CLEAR PROC
d.) PROCERR STOP

2. The SKIP command is best used for...
a.) skipping all the way to the end of a program.
b.) erasing or deleting entire files from your system.
c.) causing lines in the procedure file to be passed over.
d.) skipping the following line in the program.

3. True or false: The RUN PROC command can be used with INPUT FIELDS or RINPUT FIELDS.

Answers 12.5

NEXT:Introduction to File Processing

Back to Index