Procedures: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
m (more conversion cleanup)
Line 1: Line 1:
===Overview===
==Overview==
<p>A procedure is a sequence of input lines that can be named and saved for later use. A procedure might contain all of the lines from a User Language request that you intend to execute frequently, such as a lengthy formatted report that is run weekly. However, a procedure is not limited to a single request. It can also contain several requests, a partial request, system commands, or any combination of commands and User Language statements. A procedure can even contain text that is never executed, such as program documentation or messages to other users.    </p>
<p>
====Two types of procedures====
A procedure is a sequence of input lines that can be named and saved for later use. A procedure might contain all of the lines from a User Language request that you intend to execute frequently, such as a lengthy formatted report that is run weekly. However, a procedure is not limited to a single request. It can also contain several requests, a partial request, system commands, or any combination of commands and User Language statements. A procedure can even contain text that is never executed, such as program documentation or messages to other users.    </p>
<p>In <var class="product">Model&nbsp;204</var>, there are two types of procedures:</p>
===Two types of procedures===
<p>
In <var class="product">Model&nbsp;204</var>, there are two types of procedures:</p>
<table>
<table>
<tr class="head">
<tr class="head">
<th>Procedure type </th>
<th>Type </th>
<th>Is...</th>
<th>Description</th>
</tr>
</tr>
<tr>
<tr>
<td>Permanent </td>
<td>Permanent </td>
Line 13: Line 17:
</tr>
</tr>
<tr>
<tr>
<td>Temporary </td>
<td>Temporary </td>
<td>Saved in the system scratch file CCATEMP during the current terminal session and deleted when the user logs out.    </td>
<td>Saved in the system scratch file CCATEMP during the current terminal session and deleted when the user logs out.    </td>
</tr>
</tr>
</table>
</table>
====Procedure storage compared to request storage====
<p><var class="product">Model&nbsp;204</var> treats procedures and requests differently. Once a permanent procedure has been stored, <var class="product">Model&nbsp;204</var> saves the procedure until it is deleted or redefined, or until the file with which the procedure is associated is reinitialized. </p>
===Procedure storage compared to request storage===
<p>A User Language request, on the other hand, is temporary. (A request can be defined as any set of User Language statements which follows a BEGIN or MORE command and precedes an END statement.) A number of your most recent ad hoc requests (those newly entered at the terminal) are saved automatically as temporary procedures by <var class="product">Model&nbsp;204</var> as long as you remain logged in. Unlike permanent procedures, however, these temporary procedures are deleted by <var class="product">Model&nbsp;204</var> when you log out. The number of temporary procedures which <var class="product">Model&nbsp;204</var> saves is determined by the NORQS parameter, which has a default value of 5.</p>
<p>
====Unconditional and conditional inclusion of procedures====
<var class="product">Model&nbsp;204</var> treats procedures and requests differently. Once a permanent procedure has been stored, <var class="product">Model&nbsp;204</var> saves the procedure until it is deleted or redefined, or until the file with which the procedure is associated is reinitialized. </p>
<p>Use the INCLUDE command or statement to unconditionally include procedures. You can also include procedures conditionally, using an IF statement.</p>
<p>
====Nested procedures====
A User Language request, on the other hand, is temporary. (A request can be defined as any set of User Language statements which follows a BEGIN or MORE command and precedes an END statement.) A number of your most recent ad hoc requests (those newly entered at the terminal) are saved automatically as temporary procedures by <var class="product">Model&nbsp;204</var> as long as you remain logged in. Unlike permanent procedures, however, these temporary procedures are deleted by <var class="product">Model&nbsp;204</var> when you log out. The number of temporary procedures which <var class="product">Model&nbsp;204</var> saves is determined by the NORQS parameter, which has a default value of 5.</p>
<p>Procedures can themselves contain INCLUDE commands or statements, creating nested procedures. You can nest procedures up to four levels deep. Thus procedure A can include procedure B; procedure B can include procedure C; procedure C can include procedure D; and procedure D can include procedure E; but procedure E cannot include other procedures. See [[#Executing and defining procedures within procedures|Executing and defining procedures within procedures]] a detailed discussion of procedure nesting.              </p>
====Dummy strings====
===Unconditional and conditional inclusion of procedures===
<p>Dummy strings allow you to temporarily change certain statements within a procedure each time it is included.</p>
<p>
====Opening non-Model 204 data sets from within procedures====
Use the INCLUDE command or statement to unconditionally include procedures. You can also include procedures conditionally, using an IF statement.</p>
<p>If a User Language procedure attempts to open an already open non-<var class="product">Model&nbsp;204</var> data set at evaluation time, <var class="product">Model&nbsp;204</var> softly restarts the user with the following counting error message:</p>
===Nested procedures===
<p>
Procedures can themselves contain INCLUDE commands or statements, creating nested procedures. You can nest procedures up to four levels deep. Thus procedure A can include procedure B; procedure B can include procedure C; procedure C can include procedure D; and procedure D can include procedure E; but procedure E cannot include other procedures. See [[#Executing and defining procedures within procedures|Executing and defining procedures within procedures]] a detailed discussion of procedure nesting.              </p>
===Dummy strings===
<p>
Dummy strings allow you to temporarily change certain statements within a procedure each time it is included.</p>
===Opening non-Model 204 data sets from within procedures===
<p>
If a User Language procedure attempts to open an already open non-<var class="product">Model&nbsp;204</var> data set at evaluation time, <var class="product">Model&nbsp;204</var> softly restarts the user with the following counting error message:</p>
<p class="code">M204.2153 DATASET name IS ALREADY OPEN
<p class="code">M204.2153 DATASET name IS ALREADY OPEN
</p>
</p>
====Procedure commands====
<p>The system control commands commonly used with procedures are summarized in [[#Procedure commands|Procedure commands]]. For more information on these commands, refer to the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.</p>
===Procedure commands===
<p>
The system control commands commonly used with procedures are summarized in [[#Procedure commands|Procedure commands]].
For more information on these commands, refer to
their individual descriptions accessed via [[List of Model 204 parameters]]. </p>
<table>
<table>
<caption>Procedure control commands</caption>
<caption>Procedure control commands</caption>
Line 38: Line 58:
<th>Description</th>
<th>Description</th>
</tr>
</tr>
<tr>
<tr>
<td>DELETE</td>
<td>DELETE</td>
<td>Deletes a procedure.</td>
<td>Deletes a procedure.</td>
</tr>
</tr>
<tr>
<tr>
<td>DISPLAY</td>
<td>DISPLAY</td>
<td>Print a procedure to a terminal.</td>
<td>Print a procedure to a terminal.</td>
</tr>
</tr>
<tr>
<tr>
<td>EDIT</td>
<td>EDIT</td>
<td>Edits a procedure.</td>
<td>Edits a procedure.</td>
</tr>
</tr>
<tr>
<tr>
<td>IF</td>
<td>IF</td>
<td>Tests a condition, allows a procedure to be executed conditionally.</td>
<td>Tests a condition, allows a procedure to be executed conditionally.</td>
</tr>
</tr>
<tr>
<tr>
<td>INCLUDE</td>
<td>INCLUDE</td>
<td>Executes a procedure; procedures can be nested.</td>
<td>Executes a procedure; procedures can be nested.</td>
</tr>
</tr>
<tr>
<tr>
<td>PROCEDURE</td>
<td>PROCEDURE</td>
Line 63: Line 89:
</tr>
</tr>
</table>
</table>
===Creating a procedure===
<p>You can use the PROCEDURE command or the Full Screen Editor to define a procedure. This section discusses creating procedures primarily by means of the PROCEDURE command process. This section also includes an example of how to create a procedure and a discussion of the storage of a procedure.</p>
==Creating a procedure==
====PROCEDURE command process====
<p>
<p>You can use the PROCEDURE command to create a new procedure or to replace an existing procedure. The PROCEDURE command process has three steps: </p>
You can use the PROCEDURE command or the Full Screen Editor to define a procedure. This section discusses creating procedures primarily by means of the PROCEDURE command process. This section also includes an example of how to create a procedure and a discussion of the storage of a procedure.</p>
===PROCEDURE command process===
<p>
You can use the PROCEDURE command to create a new procedure or to replace an existing procedure. The PROCEDURE command process has three steps: </p>
<ol>
<ol>
<li>Naming the procedure</li>
<li>Naming the procedure</li>
Line 72: Line 102:
<li>Ending the procedure definition</li>
<li>Ending the procedure definition</li>
</ol>
</ol>
<b>Naming the procedure</b>
<p>To define a permanent procedure, enter the PROCEDURE command and a name, as in the following syntax and description. To define a temporary procedure, use PROCEDURE with a negative number or zero instead of a name: </p>
====Naming the procedure====
<p class="code">PROCEDURE {procname | n]
<p>
To define a permanent procedure, enter the PROCEDURE command and a name, as in the following syntax and description. To define a temporary procedure, use PROCEDURE with a negative number or zero instead of a name: </p>
<p class="syntax">PROCEDURE {<span class="term">procname</span> | <span class="term">n</span>]
</p>
</p>
<p>where procname is the identifier with which the procedure subsequently can be executed or displayed. The maximum length of procname is 255 characters, and it cannot begin with zero or a minus sign. It is normally an alphanumeric character string and must not contain any of the following special characters: </p>
<p>
where <var class="term">procname</var> is the identifier with which the procedure subsequently can be executed or displayed. The maximum length of <var class="term">procname</var> is 255 characters, and it cannot begin with zero or a minus sign. It is normally an alphanumeric character string and must not contain any of the following special characters: </p>
<ul>
<ul>
<li>Space</li>
<li>Space</li>
</li>
<li>Comma</li>
<li>Comma</li>
</li>
<li>End-of-line character</li>
<li>End-of-line character</li>
</li>
<li>Equal sign</li>
<li>Equal sign</li>
</li>
<li>Single quote</li>
<li>Single quote</li>
</li>
<li>Carriage return   </li>
<li>Carriage return  
</li>
</li>
</ul>
</ul>
<p>If you are defining a temporary procedure, remember that <var class="product">Model&nbsp;204</var> automatically assigns numbers (0, -1, -2, ...) to any ad hoc requests you create during the current terminal session, treating them as temporary procedures.</p>
<p>
<b>Entering the procedure elements</b>
If you are defining a temporary procedure, remember that <var class="product">Model&nbsp;204</var> automatically assigns numbers (0, -1, -2, ...) to any ad hoc requests you create during the current terminal session, treating them as temporary procedures.</p>
<p><var class="product">Model&nbsp;204</var> responds to the PROCEDURE command by displaying the prompt:</p>
<p class="code"><b></b>*** M204.1144: DEFINE PROCEDURE procname  
====Entering the procedure elements====
<p>
<var class="product">Model&nbsp;204</var> responds to the PROCEDURE command by displaying the prompt:</p>
<p class="code"><b></b>*** M204.1144: DEFINE PROCEDURE <i>procname</i>
</p>
</p>
<p>You can now enter commands, statements, or other text to be stored in the procedure. </p>
<p>
<p><var class="product">Model&nbsp;204</var> does not check for syntax errors as procedure lines are entered. Errors are found only when the procedure is executed.</p>
You can now enter commands, statements, or other text to be stored in the procedure. </p>
<b>Ending the procedure definition</b>
<p>
<p>When all lines for the procedure have been entered, issue the END PROCEDURE statement:</p>
<var class="product">Model&nbsp;204</var> does not check for syntax errors as procedure lines are entered. Errors are found only when the procedure is executed.</p>
<p class="code">END PROCEDURE [procname]  
====Ending the procedure definition====
<p>
When all lines for the procedure have been entered, issue the END PROCEDURE statement:</p>
<p class="syntax">END PROCEDURE [<span class="term">procname</span>]
</p>
</p>
<p>The name of the procedure after END PROCEDURE is optional.</p>
<p>
<p><var class="product">Model&nbsp;204</var> responds to the END PROCEDURE statement by displaying the message:</p>
The name of the procedure after END PROCEDURE is optional.</p>
<p class="code"><b></b>*** M204.1146: PROCEDURE procname DEFINITION ENDED  
<p>
<var class="product">Model&nbsp;204</var> responds to the END PROCEDURE statement by displaying the message:</p>
<p class="code"><b></b>*** M204.1146: PROCEDURE <i>procname</i> DEFINITION ENDED
</p>
</p>
<p>You also can enter *CANCEL or press the attention key to indicate the end of the procedure definition.</p>
<p>
====Replacing a procedure definition====
You also can enter *CANCEL or press the attention key to indicate the end of the procedure definition.</p>
<p>If you attempt to define a procedure with the same name as an existing permanent procedure, <var class="product">Model&nbsp;204</var> displays the message:</p>
<p class="code"><b></b>*** M204.1140: PROCEDURE procname ALREADY EXISTS
===Replacing a procedure definition===
<b></b>*** M204.1076: DO YOU REALLY WANT TO REPLACE?  
<p>
If you attempt to define a procedure with the same name as an existing permanent procedure, <var class="product">Model&nbsp;204</var> displays the message:</p>
<p class="code"><b></b>*** M204.1140: PROCEDURE <i>procname</i> ALREADY EXISTS
<b></b>*** M204.1076: DO YOU REALLY WANT TO REPLACE?
</p>
</p>
<p>You respond with Y or N. Entering Y erases the existing procedure and replaces it with the new one. Entering N takes you out of procedure definition mode.</p>
====Procedure aliases and security====
<p>The PROCEDURE command also has options with which you can assign an alias to the procedure name or secure the procedure by assigning it to a procedure class. The full syntax and capabilities of the PROCEDURE command are presented in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.</p>
====Creating procedures with the Full Screen Editor====
<p>A temporary procedure can be created and defined without the PROCEDURE command by using the Full Screen Editor. The procedure can be stored permanently by giving it a name when you executing the SAVE command. Refer to the Rocket <var class="product">Model&nbsp;204</var> Editing Guide for detailed information about building procedures.    </p>
====Procedure storage====
<p>Once a permanent procedure is created, it remains associated with a file until the file is reinitialized or until the procedure itself is redefined or deleted. The procedure is stored in the default file or group procedure file, or in the file specified by an IN clause on the PROCEDURE command. For more information about group procedure files, see [[Files, groups, and reference context#Procedure file and update file references|Procedure file and update file references]].</p>
<p>
<p>
You respond with Y or N. Entering Y erases the existing procedure and replaces it with the new one. Entering N takes you out of procedure definition mode.</p>
===Procedure aliases and security===
<p>
The <var>[[PROCEDURE command|PROCEDURE]]</var> command also has options with which you can assign an alias to the procedure name or secure the procedure by assigning it to a procedure class.
===Creating procedures with the Full Screen Editor===
<p>
A temporary procedure can be created and defined without the PROCEDURE command by using the Full Screen Editor. The procedure can be stored permanently by giving it a name when you executing the SAVE command.
Refer to the <var class="book">Rocket Model&nbsp;204 Editing Guide</var> for detailed information about building procedures.    </p>
===Procedure storage===
<p>
Once a permanent procedure is created, it remains associated with a file until the file is reinitialized or until the procedure itself is redefined or deleted. The procedure is stored in the default file or group procedure file, or in the file specified by an IN clause on the PROCEDURE command. For more information about group procedure files, see [[Files, groups, and reference context#Procedure file and update file references|Procedure file and update file references]].</p>
<p>
Each procedure uses at least one page of Table D. When you attempt to store a new procedure or a new version of a procedure in a file where not enough Table D space is available, <var class="product">Model&nbsp;204</var> issues a message that indicates there is insufficient space in the file to store the procedure and that the procedure definition is ended.</p>
Each procedure uses at least one page of Table D. When you attempt to store a new procedure or a new version of a procedure in a file where not enough Table D space is available, <var class="product">Model&nbsp;204</var> issues a message that indicates there is insufficient space in the file to store the procedure and that the procedure definition is ended.</p>
<p>Once the available Table D space in the file is used, neither a new procedure nor a new version of any of the file's procedures can be stored in the file until more Table D space becomes available. To make more Table D space available, you can delete procedures from the file, or the file manager can use the INCREASE command to add Table D space to the file.    </p>
<p>
====PROCEDURE process example====
Once the available Table D space in the file is used, neither a new procedure nor a new version of any of the file's procedures can be stored in the file until more Table D space becomes available. To make more Table D space available, you can delete procedures from the file, or the file manager can use the INCREASE command to add Table D space to the file.    </p>
<p>In the following example, both commands and User Language statements are included. The lines beginning with *** are <var class="product">Model&nbsp;204</var> system messages. The other lines are entered by you:</p>
===PROCEDURE process example===
<p>
In the following example, both commands and User Language statements are included. The lines beginning with <code>***</code> are <var class="product">Model&nbsp;204</var> system messages. The other lines are entered by you:</p>
<p class="code">PROCEDURE LOCATE
<p class="code">PROCEDURE LOCATE
 
<b></b>*** M204.1144: DEFINE PROCEDURE LOCATE
<b></b>*** M204.1144: DEFINE PROCEDURE LOCATE
 
OPEN VEHICLES  
OPEN VEHICLES
BEGIN
BEGIN
FORDS:    FIND ALL RECORDS FOR WHICH -
FORDS:    FIND ALL RECORDS FOR WHICH -
Line 140: Line 196:
CLOSE VEHICLES
CLOSE VEHICLES
END PROCEDURE
END PROCEDURE
 
<b></b>*** M204.1146: PROCEDURE LOCATE DEFINITION ENDED    
<b></b>*** M204.1146: PROCEDURE LOCATE DEFINITION ENDED
</p>
</p>
===Operating on procedures===
<p>This section describes the <var class="product">Model&nbsp;204</var> commands you can use to display, modify, copy, or delete procedures.</p>
==Operating on procedures==
====Displaying a procedure====
<p>
<p>As explained in this section, you can use the <var class="product">Model&nbsp;204</var> DISPLAY command to display on your terminal the text of a procedure or of multiple or all your procedures, or a list of the file's procedure names. Variations of DISPLAY also provide the following options:</p>
This section describes the <var class="product">Model&nbsp;204</var> commands you can use to display, modify, copy, or delete procedures.</p>
===Displaying a procedure===
<p>
As explained in this section, you can use the <var class="product">Model&nbsp;204</var> <var>[[DISPLAY command|DISPLAY]]</var> command to display on your terminal the text of a procedure or of multiple or all your procedures, or a list of the file's procedure names. Variations of DISPLAY also provide the following options:</p>
<ul>
<ul>
<li>Procedure aliases</li>
<li>Procedure aliases</li>
</li>
<li>Procedure names</li>
<li>Procedure names</li>
</li>
<li>Numbers for procedure text lines</li>
<li>Numbers for procedure text lines</li>
</li>
<li>Procedure classes</li>
<li>Procedure classes</li>
</li>
<li>Access rights for various procedure classes </li>
<li>Access rights for various procedure classes  
</li>
</li>
</ul>
</ul>
<p>The full syntax and capabilities of the DISPLAY command are presented in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual. Procedure aliases, classes and access rights are described later in this chapter.</p>
<p>
<b>Displaying the text of a procedure</b>
Procedure aliases, classes and access rights are described later in this page.</p>
<p>The DISPLAY command allows you to display a procedure. The command is entered in this form:      </p>
<p class="code">DISPLAY [PROCEDURE] [procname | n}
====Displaying the text of a procedure====
<p>
The DISPLAY command allows you to display a procedure. The command is entered in this form:      </p>
<p class="syntax">DISPLAY [PROCEDURE] [<span class="term">procname</span> | <span class="term">n</span>}
</p>
</p>
<p>To display a temporary procedure, do not specify a name. Specify zero or a negative number (-n), where n is no higher than the maximum allowable number of temporary procedures.</p>
<p>
<p>Entering the command DISPLAY by itself, without specifying a name, a number, or zero, displays temporary procedure 0.</p>
To display a temporary procedure, do not specify a name. Specify zero or a negative number (-n), where n is no higher than the maximum allowable number of temporary procedures.</p>
<p><var class="product">Model&nbsp;204</var> displays the contents of the specified procedure on your terminal, unless the DISPLAY command is preceded by the USE command. In this case the procedure is displayed on the alternate output destination associated with the USE command. See the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual for a full explanation of USE facilities.</p>
<p>
<b>Displaying multiple procedures</b>
Entering the command DISPLAY by itself, without specifying a name, a number, or zero, displays temporary procedure 0.</p>
<p>The DISPLAY command can also be used to display multiple procedures simultaneously. </p>
<p>
<p>For example, the following command displays four procedures:</p>
<var class="product">Model&nbsp;204</var> displays the contents of the specified procedure on your terminal, unless the DISPLAY command is preceded by the USE command. In this case the procedure is displayed on the alternate output destination associated with the USE command.
<p class="code">DISPLAY PROCEDURE TEST ALPHA -3 0  
see [[USE command: Directing output]] for a full explanation of USE facilities.</p>
====Displaying multiple procedures====
<p>
The DISPLAY command can also be used to display multiple procedures simultaneously. </p>
<p>
For example, the following command displays four procedures:</p>
<p class="code">DISPLAY PROCEDURE TEST ALPHA -3 0
</p>
</p>
<p>To display all procedures currently defined for the default file, enter:</p>
<p>
<p class="code">DISPLAY PROCEDURE ALL  
To display all procedures currently defined for the default file, enter:</p>
<p class="code">DISPLAY PROCEDURE ALL
</p>
</p>
<p>This version of the command does not display temporary procedures.</p>
<p>
<p>To display the names of the permanent procedures defined for the default file, enter:</p>
This version of the command does not display temporary procedures.</p>
<p class="code">DISPLAY LIST  
<p>
To display the names of the permanent procedures defined for the default file, enter:</p>
<p class="code">DISPLAY LIST
</p>
</p>
====Modifying a procedure====
<p>The <var class="product">Model&nbsp;204</var> Full Screen Editor and Line Editor allow you to modify procedures online. Use the EDIT command to enter the Editor environment and make your changes. For information about using the Editor, see the Rocket <var class="product">Model&nbsp;204</var> Editing Guide.</p>
===Modifying a procedure===
====Copying a procedure====
<p>
<p>You can also use the Full Screen Editor and Line Editor to copy procedures. To copy a procedure, specify a second procedure name in the EDIT command. For example, if you enter the following:</p>
The <var class="product">Model&nbsp;204</var> Full Screen Editor and Line Editor allow you to modify procedures online.
<p class="code">EDIT OLD, NEW  
Use the EDIT command to enter the Editor environment and make your changes.
For information about using the Editor, see the <var class="book">Rocket Model&nbsp;204 Editing Guide</var>. </p>
===Copying a procedure===
<p>
You can also use the Full Screen Editor and Line Editor to copy procedures. To copy a procedure, specify a second procedure name in the EDIT command. For example, if you enter the following:</p>
<p class="code">EDIT OLD, NEW
</p>
</p>
<p>then the edited version of procedure OLD is stored in procedure NEW.</p>
<p>
<p>Full Screen Editor and Line Editor operations are described in the discussion on the EDIT command in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual and the Rocket <var class="product">Model&nbsp;204</var> Editing Guide.</p>
then the edited version of procedure OLD is stored in procedure NEW.</p>
<p>You can also use the COPY PROCEDURE command to copy procedures.   </p>
<p>
====Deleting a procedure====
Full Screen Editor and Line Editor operations are described
<p>To delete a permanent or temporary procedure, enter:</p>
in [[EDIT command]]. </p>
<p class="code">DELETE PROCEDURE procname  
<p>
You can also use the <var>[[COPY PROCEDURE command|COPY PROCEDURE]]</var> command to copy procedures. </p>
===Deleting a procedure===
<p>
To delete a permanent or temporary procedure, enter:</p>
<p class="syntax">DELETE PROCEDURE <span class="term">procname</span>
</p>
</p>
<p>or:</p>
<p>
<p class="code">DELETE PROCEDURE n  
or:</p>
<p class="syntax">DELETE PROCEDURE <span class="term">n</span>
</p>
</p>
<p>When a procedure is deleted, <var class="product">Model&nbsp;204</var> recovers all of the space that the procedure occupied in the file.</p>
<p>
<b>Procedure names consisting of special characters</b>
When a procedure is deleted, <var class="product">Model&nbsp;204</var> recovers all of the space that the procedure occupied in the file.</p>
<p>If a procedure's name consists of special characters (for example, ) or _ ), you must enclose the procedure's name in quotes when deleting it. For example, the following command fails:</p>
====Procedure names consisting of special characters====
<p>
If a procedure's name consists of special characters (for example, <code>)</code> or <code>_</code> ), you must enclose the procedure's name in quotes when deleting it. For example, the following command fails:</p>
<p class="code">DELETE PROCEDURE )
<p class="code">DELETE PROCEDURE )
</p>
</p>
<p>However, this next command succeeds:</p>
<p>
However, this next command succeeds:</p>
<p class="code">DELETE PROCEDURE ')'
<p class="code">DELETE PROCEDURE ')'
</p>
</p>
<b>Deleting procedure aliases with DEASSIGN</b>
<p>The DELETE PROCEDURE command does not delete any aliases assigned to the procedure being deleted. The DEASSIGN command must be issued to delete a procedure alias. </p>
====Deleting procedure aliases with DEASSIGN====
<ul>
<p>
<li>Aliases are described in [[#Using procedure aliases|Using procedure aliases]]</li>
The DELETE PROCEDURE command does not delete any aliases assigned to
</li>
the procedure being deleted.
<li>DEASSIGN command is described in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.</li>
The <var>[[DEASSIGN command|DEASSIGN]]</var> command must be issued to delete a procedure alias. </p>
</li>
<p>Aliases are described in [[#Using procedure aliases|Using procedure aliases]]</p>
</ul>
===Unconditional and conditional execution of procedures===
==Unconditional and conditional execution of procedures==
<p>You can include (execute) a procedure unconditionally in one of two ways:  </p>
<p>
You can include (execute) a procedure unconditionally in one of two ways:  </p>
<ul>
<ul>
<li>Submitting a stand-alone procedure by specifying an INCLUDE command at the terminal</li>
<li>Submitting a stand-alone procedure by specifying an INCLUDE command at the terminal</li>
<li>Including a procedure in a request by specifying an INCLUDE statement in the User Language request </li>
<li>Including a procedure in a request by specifying an INCLUDE statement in the User Language request </li>
</ul>
</ul>
<p>A procedure invoked by an INCLUDE command or statement can contain several requests and system control commands. INCLUDE, used as a command or a statement, is unconditional.      </p>
<p>
====INCLUDE statement====
A procedure invoked by an INCLUDE command or statement can contain several requests and system control commands. INCLUDE, used as a command or a statement, is unconditional.      </p>
<b>Description</b>
<p>You can unconditionally include another procedure within a User Language request by specifying the INCLUDE statement in the request.    </p>
===INCLUDE statement===
<b>Syntax</b>
<p>The basic form of the INCLUDE statement is:</p>
====Description====
<p class="code">INCLUDE {procname | n}
<p>
You can unconditionally include another procedure within a User Language request by specifying the INCLUDE statement in the request.    </p>
====Syntax====
<p>
The basic form of the INCLUDE statement is:</p>
<p class="syntax">INCLUDE {<span class="term">procname</span> | <span class="term">n</span>}
</p>
</p>
<b>Where</b>
Where:
<ul>
<ul>
<li>procname specifies the name of the permanent procedure to be included.</li>
<li><var class="term">procname</var> specifies the name of the permanent procedure to be included.</li>
</li>
 
<li>n specifies the number of the temporary procedure to be included. Temporary procedures are always referred to by numbers. The temporary procedure most recently entered is always procedure 0. See [[#Working with temporary procedures|Working with temporary procedures]].</li>
<li><var class="term">n</var> specifies the number of the temporary procedure to be included. Temporary procedures are always referred to by numbers. The temporary procedure most recently entered is always procedure 0. See [[#Working with temporary procedures|Working with temporary procedures]].  
</li>
</li>
</ul>
</ul>
<b>Processing</b>
<p>During evaluation, the lines of the named procedure are inserted where the INCLUDE statement appears in the request. </p>
====Processing====
<b>Example</b>
<p>
<p>Suppose an audit department wants the first page of all its reports to have one standard format. The department would define a procedure as follows:</p>
During evaluation, the lines of the named procedure are inserted where the INCLUDE statement appears in the request. </p>
====Example====
<p>
Suppose an audit department wants the first page of all its reports to have one standard format. The department would define a procedure as follows:</p>
<p class="code">PROCEDURE TITLEPAGE
<p class="code">PROCEDURE TITLEPAGE
           SET HEADER 2 'MORTON INSURANCE CO.' AT COLUMN 9
           SET HEADER 2 'MORTON INSURANCE CO.' AT COLUMN 9
Line 241: Line 342:
           SET HEADER 5 'AUDIT DEPARTMENT' AT COLUMN 11
           SET HEADER 5 'AUDIT DEPARTMENT' AT COLUMN 11
           NEW PAGE
           NEW PAGE
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>Thus the request:</p>
<p>
Thus the request:</p>
<p class="code">BEGIN
<p class="code">BEGIN
             INCLUDE TITLEPAGE
             INCLUDE TITLEPAGE
Line 254: Line 356:
POL.HOLDERS: IN CLIENTS FIND ALL RECORDS FOR WHICH
POL.HOLDERS: IN CLIENTS FIND ALL RECORDS FOR WHICH
                 RECTYPE = POLICYHOLDER
                 RECTYPE = POLICYHOLDER
             END FIND  
             END FIND
PRINT.REC:  FOR EACH RECORD IN POL.HOLDERS
PRINT.REC:  FOR EACH RECORD IN POL.HOLDERS
                 PRINT FULLNAME AT COLUMN 3 -
                 PRINT FULLNAME AT COLUMN 3 -
                   WITH POLICY NO TO COLUMN 35
                   WITH POLICY NO TO COLUMN 35
             END FOR
             END FOR
END  
END
</p>
</p>
<p>would produce a report in the format shown below.</p>
<p>
<p>The first page is headed:</p>
would produce a report in the format shown below.</p>
<p>
The first page is headed:</p>
<p class="code">99.218 AUG 06 09.05.00          PAGE 1
<p class="code">99.218 AUG 06 09.05.00          PAGE 1
 
         MORTON INSURANCE CO.
         MORTON INSURANCE CO.
           FISCAL YEAR 1990
           FISCAL YEAR 1990
 
           AUDIT DEPARTMENT  
           AUDIT DEPARTMENT
</p>
</p>
<p>All subsequent pages are formatted:</p>
<p>
All subsequent pages are formatted:</p>
<p class="code">99.218 AUG 06 09.05.01          PAGE 2
<p class="code">99.218 AUG 06 09.05.01          PAGE 2
 
         POLICYHOLDERS REPORT
         POLICYHOLDERS REPORT
 
   NAME                    POLICY NO.
   NAME                    POLICY NO.
 
   ABBOTT, FRANKLIN G      100340
   ABBOTT, FRANKLIN G      100340
   ABBOTT, HAZEL W          100642
   ABBOTT, HAZEL W          100642
     .                      .
     .                      .
     .                      .
     .                      .
     .                      .  
     .                      .
</p>
</p>
====INCLUDE command====
<p>You can unconditionally execute a procedure by using the INCLUDE command. The syntax of the INCLUDE command is the same as that of the INCLUDE statement. If you enter the INCLUDE command without specifying a procedure name or number, <var class="product">Model&nbsp;204</var> executes the most recently entered temporary procedure (procedure 0). For a detailed description of the INCLUDE command, refer to the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.    </p>
===INCLUDE command===
<b>Processing</b>
<p>
<p>When <var class="product">Model&nbsp;204</var> encounters an INCLUDE command, it reads the lines stored in the procedure and executes each system control command in the procedure. Any User Language requests in the procedure are compiled and executed.</p>
You can unconditionally execute a procedure by using the <var>[[INCLUDE command|INCLUDE]]</var> command.
<p>The following commands cannot be issued from within a procedure:</p>
The syntax of the INCLUDE command is the same as that of the INCLUDE statement. If you enter the INCLUDE command without specifying a procedure name or number, <var class="product">Model&nbsp;204</var> executes the most recently entered temporary procedure (procedure 0). </p>
====Processing====
<p>
When <var class="product">Model&nbsp;204</var> encounters an INCLUDE command, it reads the lines stored in the procedure and executes each system control command in the procedure. Any User Language requests in the procedure are compiled and executed.</p>
<p>
The following commands cannot be issued from within a procedure:</p>
<ul>
<ul>
<li>CREATEG</li>
<li>CREATEG</li>
Line 312: Line 423:
</li>
</li>
</ul>
</ul>
<p>Responses to dummy strings and $READ prompts can be specified as part of the INCLUDE command or statement, as described in [[#Dummy strings in procedures|Dummy strings in procedures]].    </p>
<p>
<b>Example</b>
Responses to dummy strings and $READ prompts can be specified as part of the INCLUDE command or statement, as described in [[#Dummy strings in procedures|Dummy strings in procedures]].    </p>
<p>If a procedure is included at command level, any User Language statements in the procedure must be preceded by a BEGIN or a MORE command. A procedure can contain several requests and also can contain any number of valid system control commands. For example:</p>
====Example====
<p>
If a procedure is included at command level, any User Language statements in the procedure must be preceded by a BEGIN or a MORE command. A procedure can contain several requests and also can contain any number of valid system control commands. For example:</p>
<p class="code">PROCEDURE PRINTS
<p class="code">PROCEDURE PRINTS
 
<b></b>*** M204.1144: DEFINE PROCEDURE PRINTS
<b></b>*** M204.1144: DEFINE PROCEDURE PRINTS
 
BEGIN  
BEGIN
   PRINT 'FIRST REQUEST'
   PRINT 'FIRST REQUEST'
END
END
Line 328: Line 442:
RESET LECHO = 0
RESET LECHO = 0
END PROCEDURE
END PROCEDURE
 
<b></b>*** M204.1146: PROCEDURE PRINTS DEFINITION ENDED
<b></b>*** M204.1146: PROCEDURE PRINTS DEFINITION ENDED
</p>
</p>
<p>This procedure, PRINTS, includes END statements for the requests contained within the procedure. The PROCEDURE PRINTS and  
<p>
This procedure, PRINTS, includes END statements for the requests contained within the procedure. The PROCEDURE PRINTS and
END PROCEDURE commands are not stored as part of the procedure.</p>
END PROCEDURE commands are not stored as part of the procedure.</p>
<p>To execute this procedure, enter:</p>
<p>
<p class="code">INCLUDE PRINTS
To execute this procedure, enter:</p>
<p class="code">INCLUDE PRINTS
</p>
</p>
<p>The following display appears:</p>
<p>
The following display appears:</p>
<p class="code">FIRST REQUEST
<p class="code">FIRST REQUEST
BEGIN
BEGIN
Line 342: Line 459:
END
END
SECOND REQUEST
SECOND REQUEST
RESET LECHO = 0    
RESET LECHO = 0
</p>
</p>
<p>In this case, the INCLUDE command is not labeled, because it appears as a command rather than in a request.    </p>
<p>
====Conditional inclusion of procedures====
In this case, the INCLUDE command is not labeled, because it appears as a command rather than in a request.    </p>
<p>The IF command allows a procedure to be included conditionally, depending on the result of a specified test. It is issued in the form:</p>
<p class="code">IF X=Z, procname  
===Conditional inclusion of procedures===
<p>
The IF command allows a procedure to be included conditionally, depending on the result of a specified test. It is issued in the form:</p>
<p class="syntax">IF X=Z, <span class="term">procname</span>
</p>
</p>
<p>where the named procedure is included if the condition is satisfied (in the example, if the global variable X has a value of Z). </p>
<p>
<p>Dummy string and $READ responses can be specified as an option on the IF command line. The IF command and techniques for conditionally including procedures using global variables, are described in [[Global features]] and in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.                       </p>
where the named procedure is included if the condition is satisfied (in the example, if the global variable X has a value of Z). </p>
===Using procedure aliases===
<p>
<p>A procedure can have more than one name: an actual or official name and any number of alternative names or aliases. For example, the official name might be short and easy to enter and the aliases might be longer and more descriptive. All the names can be used interchangeably. However, access to a procedure by its actual name is slightly faster than access by an alias.</p>
Dummy string and $READ responses can be specified as an option on
====Defining and deleting aliases====
the <var>[[IF command|IF]]</var> command line.
<p>You can define an alias with the PROCEDURE command, such as the following:</p>
For information about techniques for conditionally including procedures using global variables, see [[Global features]]. </p>
<p class="code">PROCEDURE COUNT ALIAS=FEMALE.COUNT  
==Using procedure aliases==
<p>
A procedure can have more than one name: an actual or official name and any number of alternative names or aliases. For example, the official name might be short and easy to enter and the aliases might be longer and more descriptive. All the names can be used interchangeably. However, access to a procedure by its actual name is slightly faster than access by an alias.</p>
===Defining and deleting aliases===
<p>
You can define an alias with the PROCEDURE command, such as the following:</p>
<p class="code">PROCEDURE COUNT ALIAS=FEMALE.COUNT
</p>
</p>
<p>An alias also can be assigned after a procedure is defined with the ASSIGN command:</p>
<p>
<p class="code">ASSIGN COUNT,FEMALE.COUNT  
An alias also can be assigned after a procedure is defined with the ASSIGN command:</p>
<p class="code">ASSIGN COUNT,FEMALE.COUNT
</p>
</p>
<p>When a new alias is assigned for a procedure, all existing aliases are preserved.</p>
<p>
<p>An alias remains in effect until it is removed by entering a DEASSIGN command. For example:</p>
When a new alias is assigned for a procedure, all existing aliases are preserved.</p>
<p class="code">DEASSIGN FEMALE.COUNT  
<p>
An alias remains in effect until it is removed by entering a DEASSIGN command. For example:</p>
<p class="code">DEASSIGN FEMALE.COUNT
</p>
</p>
<p>Deleting the procedure does not automatically delete any aliases that have been established for the procedure. Only the DEASSIGN command removes aliases.</p>
<p>
====Aliases not legal with RENAME====
Deleting the procedure does not automatically delete any aliases that have been established for the procedure. Only the DEASSIGN command removes aliases.</p>
<p>With nearly all of the <var class="product">Model&nbsp;204</var> commands, a procedure alias can be used interchangeably with the official procedure name. When editing, executing, displaying, or deleting a procedure, you can identify the procedure by specifying either its name or its alias. However, if you are changing the official name of a procedure with the RENAME command:</p>
<p class="code">RENAME COUNT, COMPUTE  
===Aliases not legal with RENAME===
<p>
With nearly all of the <var class="product">Model&nbsp;204</var> commands, a procedure alias can be used interchangeably with the official procedure name. When editing, executing, displaying, or deleting a procedure, you can identify the procedure by specifying either its name or its alias. However, if you are changing the official name of a procedure with the RENAME command:</p>
<p class="code">RENAME COUNT, COMPUTE
</p>
</p>
<p>you must specify the actual name (not an alias) in the command.            </p>
<p>
===Protecting procedure access and manipulation===
you must specify the actual name (not an alias) in the command.            </p>
<p>The procedures in a file are not automatically available to all users. They might be available only for certain users or for certain operations. Procedure access and manipulation are protected by file-level and procedure-level security. This section provides a brief description of the two layers of procedure protection. For a complete discussion of file and procedure security, see the Rocket <var class="product">Model&nbsp;204</var> File Manager's Guide. </p>
====Procedure protection====
==Protecting procedure access and manipulation==
<p>Procedure protection involves the control of user privileges and procedure accessibility. You must have both of the following to use a given procedure in a file:</p>
<p>
The procedures in a file are not automatically available to all users. They might be available only for certain users or for certain operations. Procedure access and manipulation are protected by file-level and procedure-level security. This section provides a brief description of the two layers of procedure protection.
For a complete discussion of file and procedure security, see [[Security]]. </p>
===Procedure protection===
<p>
Procedure protection involves the control of user privileges and procedure accessibility. You must have both of the following to use a given procedure in a file:</p>
<ul>
<ul>
<li>Privileges that entitle you to operate on (define, modify, delete, and so on) procedures to which you have access. These privileges, or access rights, might permit some procedure operations but not others. </li>
<li>Privileges that entitle you to operate on (define, modify, delete, and so on) procedures to which you have access. These privileges, or access rights, might permit some procedure operations but not others. </li>
Line 380: Line 520:
</li>
</li>
</ul>
</ul>
<b>Access rights</b>
<p>Access rights are a subset of file privileges. When you open a file, you are granted certain file privileges according to the file type and your password, if any. These privileges include the operations on procedures, if any, you are permitted. At this time you are also assigned to a user class, all members of which have the same access rights. Your user class, an arbitrary number in the range 1 through 255, is used in the determination of whether you can access a given procedure. </p>
====Access rights====
<p>The access rights for your user class can also later be modified for some or all procedures if the file manager secures file procedures. </p>
<p>
<p>See the note on the following page for more information about the effect on privilege determination of modifications to access rights. For more information about file privileges, see the Rocket <var class="product">Model&nbsp;204</var> File Manager's Guide.</p>
Access rights are a subset of file privileges. When you open a file, you are granted certain file privileges according to the file type and your password, if any. These privileges include the operations on procedures, if any, you are permitted. At this time you are also assigned to a user class, all members of which have the same access rights. Your user class, an arbitrary number in the range 1 through 255, is used in the determination of whether you can access a given procedure. </p>
<b>Gaining procedure access</b>
<p>
<p>The Access Control Table (ACT) included in each file associates users with the procedures they can access. The table holds your file privileges and user class and maps them to the procedure class of the procedures you can access. A procedure class is a number (like user class) assigned to a procedure with the PROCEDURE command or the SECURE command to protect it from unauthorized access. </p>
The access rights for your user class can also later be modified for some or all procedures if the file manager secures file procedures. </p>
<p>When you attempt to use a command that operates on a procedure, <var class="product">Model&nbsp;204</var> checks the Access Control Table. The ACT simultaneously determines whether you can access the procedure and what access rights you have for the procedure. You are allowed to execute the command or you receive a message that you are not authorized to do so. </p>
<p>
====Defining procedure classes====
See the note on the following page for more information about the effect on privilege determination of modifications to access rights. For more information about file privileges, see [[Security#File privileges|File privileges]]. </p>
<p>Most privileges and other security features at an installation are assigned by the system manager and the file manager. However, users with sufficient user privileges can secure a procedure by assigning the procedure a class when it is defined, as in the following example:</p>
<p class="code">PROCEDURE procname PCLASS = n  
====Gaining procedure access====
<p>
The Access Control Table (ACT) included in each file associates users with the procedures they can access. The table holds your file privileges and user class and maps them to the procedure class of the procedures you can access. A procedure class is a number (like user class) assigned to a procedure with the PROCEDURE command or the SECURE command to protect it from unauthorized access. </p>
<p>
When you attempt to use a command that operates on a procedure, <var class="product">Model&nbsp;204</var> checks the Access Control Table. The ACT simultaneously determines whether you can access the procedure and what access rights you have for the procedure. You are allowed to execute the command or you receive a message that you are not authorized to do so. </p>
===Defining procedure classes===
<p>
Most privileges and other security features at an installation are assigned by the system manager and the file manager. However, users with sufficient user privileges can secure a procedure by assigning the procedure a class when it is defined, using the following format:</p>
<p class="syntax">PROCEDURE <span class="term">procname</span> PCLASS = <span class="term">n</span>
</p>
</p>
<p>where n, a number in the range 1 through 255, is the desired procedure class. </p>
<p>
<p>When you are defining a new procedure, <var class="product">Model&nbsp;204</var> checks your access rights (see the following Note) to determine whether you are allowed to define procedures of the class specified. If you want to redefine an existing nonsecured procedure by adding a class to it, you must have the privilege to change procedures of the specified class. If the procedure being redefined is already secured, you cannot change its class unless you have file manager privileges.</p>
where <var class="term">n</var>, a number in the range 1 through 255, is the desired procedure class. </p>
<p>
When you are defining a new procedure, <var class="product">Model&nbsp;204</var> checks your access rights (see the following Note) to determine whether you are allowed to define procedures of the class specified. If you want to redefine an existing nonsecured procedure by adding a class to it, you must have the privilege to change procedures of the specified class. If the procedure being redefined is already secured, you cannot change its class unless you have file manager privileges.</p>
<p class="note"><b>Note:</b> To determine your access rights with regard to a specific operation on a procedure to which you have access, <var class="product">Model&nbsp;204</var> first checks whether your file privileges allow you to perform the operation. If they do, <var class="product">Model&nbsp;204</var> then checks whether the procedure has been SECUREd. If it has, and if your secured rights do not allow the operation you are attempting, you are informed that you lack authorization to perform the operation.</p>
<p class="note"><b>Note:</b> To determine your access rights with regard to a specific operation on a procedure to which you have access, <var class="product">Model&nbsp;204</var> first checks whether your file privileges allow you to perform the operation. If they do, <var class="product">Model&nbsp;204</var> then checks whether the procedure has been SECUREd. If it has, and if your secured rights do not allow the operation you are attempting, you are informed that you lack authorization to perform the operation.</p>
====Controlling procedure security====
<p>The file manager can secure existing procedures and also can desecure procedures. The SECURE command secures a procedure by assigning a procedure class to it. SECURE can also limit particular user classes to particular procedure classes. Finally, SECURE can also assign particular procedure operations to particular user classes.</p>
===Controlling procedure security===
<p>The DESECURE command desecures privileges or removes access rights for particular user or procedure classes. </p>
<p>
<p>For more information:</p>
The file manager can secure existing procedures and also can desecure procedures.
<ul>
The <var>[[SECURE command|SECURE]]</var> command secures a procedure by assigning a procedure class to it. SECURE can also limit particular user classes to particular procedure classes. Finally, SECURE can also assign particular procedure operations to particular user classes.</p>
<li>The SECURE and DESECURE commands are described in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual. </li>
<p>
</li>
The <var>[[DESECURE command|DESECURE]]</var> command desecures privileges or removes access rights for particular user or procedure classes. </p>
<li><var class="product">Model&nbsp;204</var> security features are described in greater detail in the Rocket <var class="product">Model&nbsp;204</var> File Manager's Guide.           </li>
<p>
</li>
For more information about
</ul>
<var class="product">Model&nbsp;204</var> security features, see [[Security]].
===Executing and defining procedures within procedures===
</p>
<p>Procedures can have a layered construction: they can contain INCLUDEs for other procedures, and they can contain other procedure definitions. </p>
<p>Each of these constructions is discussed in this section.</p>
==Executing and defining procedures within procedures==
====Nested procedures====
<p>
<p>Procedures that contain INCLUDE commands and statements are called nested. Procedure nesting can be as many as four levels deep. Thus, procedure A can unconditionally include procedure B; procedure B can unconditionally include procedure C; procedure C can unconditionally include procedure D; and procedure D can unconditionally include procedure E. However, procedure E cannot include additional procedures if procedure A is executed.</p>
Procedures can have a layered construction: they can contain INCLUDEs for other procedures, and they can contain other procedure definitions. </p>
<p>You can use the LVLTRC parameter as a debugging tool to trace the level of nesting.</p>
<p>
<b>Example</b>
Each of these constructions is discussed in this section.</p>
<p>The following example illustrates the order in which <var class="product">Model&nbsp;204</var> reads the lines of nested procedures. </p>
<p>The procedures to be used are defined as follows:</p>
===Nested procedures===
<p>Procedure A: </p>
<p>
Procedures that contain INCLUDE commands and statements are called nested. Procedure nesting can be as many as four levels deep. Thus, procedure A can unconditionally include procedure B; procedure B can unconditionally include procedure C; procedure C can unconditionally include procedure D; and procedure D can unconditionally include procedure E. However, procedure E cannot include additional procedures if procedure A is executed.</p>
<p>
You can use the LVLTRC parameter as a debugging tool to trace the level of nesting.</p>
====Example====
<p>
The following example illustrates the order in which <var class="product">Model&nbsp;204</var> reads the lines of nested procedures. </p>
<p>
The procedures to be used are defined as follows:</p>
<p>
Procedure A: </p>
<p class="code">INCLUDE B
<p class="code">INCLUDE B
INCLUDE C
INCLUDE C
</p>
</p>
<p>Procedure B: </p>
<p>
Procedure B: </p>
<p class="code">BEGIN
<p class="code">BEGIN
INCLUDE D
INCLUDE D
END
END
</p>
</p>
<p>Procedure C: </p>
<p>
Procedure C: </p>
<p class="code">BEGIN
<p class="code">BEGIN
PRINT 'END OF REQUEST'
PRINT 'END OF REQUEST'
Line 428: Line 592:
TIME
TIME
</p>
</p>
<p>Procedure D: </p>
<p>
Procedure D: </p>
<p class="code">NAMES:  FIND ALL RECORDS FOR WHICH -
<p class="code">NAMES:  FIND ALL RECORDS FOR WHICH -
         NAME = SMITH
         NAME = SMITH
Line 442: Line 607:
BEGIN
BEGIN
CTR:    FIND AND PRINT COUNT -
CTR:    FIND AND PRINT COUNT -
         NAME = JONES  
         NAME = JONES
</p>
</p>
<p>When you enter INCLUDE A, <var class="product">Model&nbsp;204</var> reads the lines in the following order:</p>
<p>
<p class="code">INCLUDE B
When you enter INCLUDE A, <var class="product">Model&nbsp;204</var> reads the lines in the following order:</p>
<p class="code">INCLUDE B
BEGIN
BEGIN
 
INCLUDE D
INCLUDE D
NAMES: FIND ALL RECORDS FOR WHICH -
NAMES: FIND ALL RECORDS FOR WHICH -
       NAME = SMITH
       NAME = SMITH
Line 462: Line 628:
       NAME = JONES
       NAME = JONES
END
END
 
INCLUDE C
INCLUDE C
BEGIN
BEGIN
PRINT 'END OF REQUEST'
PRINT 'END OF REQUEST'
END
END
TIME      
TIME
</p>
</p>
====Defining a procedure within a procedure====
<p>You can define procedures from within another procedure. Inner, defined, procedures can be established from the execution of the outer, defining, procedure. The inner procedure is not actually defined until the first procedure is executed. </p>
===Defining a procedure within a procedure===
<b>Example</b>
<p>
<p>Entering the statement lines in the following example creates a procedure named MAKE.PROC. When the procedure executes, it prompts you for input and creates the FIND.AND.COUNT procedure with the selection criteria entered from the terminal.</p>
You can define procedures from within another procedure. Inner, defined, procedures can be established from the execution of the outer, defining, procedure. The inner procedure is not actually defined until the first procedure is executed. </p>
<p class="code">PROCEDURE MAKE.PROC  
====Example====
<p>
Entering the statement lines in the following example creates a procedure named MAKE.PROC. When the procedure executes, it prompts you for input and creates the FIND.AND.COUNT procedure with the selection criteria entered from the terminal.</p>
<p class="code">PROCEDURE MAKE.PROC
BEGIN
BEGIN
IF $SETG('GLOB','??ENTER.FIND.SPEC') THEN
IF $SETG('GLOB','??ENTER.FIND.SPEC') THEN
Line 488: Line 658:
END
END
END PROCEDURE FIND.AND.COUNT
END PROCEDURE FIND.AND.COUNT
END PROCEDURE  
END PROCEDURE
</p>
</p>
<b>Setting dummy string substitution</b>
<p>As the example shows, variable parts of the inner procedure can be specified as dummy strings. (Refer to [[#Dummy strings in procedures|Dummy strings in procedures]].) When the <var class="product">Model&nbsp;204</var> SUB parameter is set to 4 (substitution is made in lines from procedures), substitutions are made for dummy strings during execution of the defining procedure. The resulting values are used in the establishment of the defined procedure. To establish a defined procedure that contains dummy strings from within another procedure, option 4 of the SUB parameter must be turned off. </p>
====Setting dummy string substitution====
====Identifying the procedure ending====
<p>
<p>Procedure definition is invoked by a PROCEDURE command followed by the procedure name. Subsequent lines are stored as the procedure definition. The end of the procedure definition is indicated by END PROCEDURE. The procedure name can follow END PROCEDURE. For an inner procedure, the procedure name should be appended to the END PROCEDURE.</p>
As the example shows, variable parts of the inner procedure can be specified as dummy strings. (Refer to [[#Dummy strings in procedures|Dummy strings in procedures]].) When the <var class="product">Model&nbsp;204</var> SUB parameter is set to 4 (substitution is made in lines from procedures), substitutions are made for dummy strings during execution of the defining procedure. The resulting values are used in the establishment of the defined procedure. To establish a defined procedure that contains dummy strings from within another procedure, option 4 of the SUB parameter must be turned off. </p>
<p>If the procedure name is entered after END PROCEDURE and the name does not match the name of the outer, defining procedure, the procedure definition is not ended: <var class="product">Model&nbsp;204</var> assumes the END PROCEDURE statement is another line of the procedure. Only an END PROCEDURE command without a procedure name or with a procedure name that matches the name of the defining procedure completes the procedure definition.      </p>
===Working with temporary procedures===
===Identifying the procedure ending===
<p><var class="product">Model&nbsp;204</var> automatically saves a limited number of a user's most recent requests as temporary procedures. The number of saved requests is controlled by the NORQS parameter, which has a default value of 5.</p>
<p>
<p>During the current terminal session, recent ad hoc requests are treated like permanent procedures. They can be executed, displayed, and deleted with the commands described elsewhere in this chapter. Unlike permanent procedures, however, temporary procedures cannot be named. You can assign them a number or they can be assigned a number automatically by <var class="product">Model&nbsp;204</var>.</p>
Procedure definition is invoked by a PROCEDURE command followed by the procedure name. Subsequent lines are stored as the procedure definition. The end of the procedure definition is indicated by END PROCEDURE. The procedure name can follow END PROCEDURE. For an inner procedure, the procedure name should be appended to the END PROCEDURE.</p>
====Defining a temporary procedure====
<p>
<p>If a request is entered from your terminal rather than from a stored procedure, it is known as an ad hoc request. Ad hoc requests are referred to by numbers. Request 0 is either the request that is currently being entered or, if no request is being entered, the most recently entered request. Request -1 refers to the request entered before the most recent one, -2 to the one before that, and so on.</p>
If the procedure name is entered after END PROCEDURE and the name does not match the name of the outer, defining procedure, the procedure definition is not ended: <var class="product">Model&nbsp;204</var> assumes the END PROCEDURE statement is another line of the procedure. Only an END PROCEDURE command without a procedure name or with a procedure name that matches the name of the defining procedure completes the procedure definition.      </p>
<p>You can also define the number of a temporary procedure explicitly by assigning it a negative number in the PROCEDURE command. </p>
<p>Temporary procedures and ad hoc requests use the same numbering system. NORQS, a UTABLE parameter, determines the total number of temporary procedures and requests. </p>
==Working with temporary procedures==
<p>A temporary procedure can contain commands and other text and need not be only a simple User Language request. </p>
<p>
====Avoiding the loss of the oldest temporary procedure====
<var class="product">Model&nbsp;204</var> automatically saves a limited number of a user's most recent requests as temporary procedures. The number of saved requests is controlled by the NORQS parameter, which has a default value of 5.</p>
<p>When a new request is entered by entering either of the following commands:</p>
<p>
<p class="code">BEGIN  
During the current terminal session, recent ad hoc requests are treated like permanent procedures. They can be executed, displayed, and deleted with the commands described elsewhere in this page.
Unlike permanent procedures, however, temporary procedures cannot be named. You can assign them a number or they can be assigned a number automatically by <var class="product">Model&nbsp;204</var>.</p>
===Defining a temporary procedure===
<p>
If a request is entered from your terminal rather than from a stored procedure, it is known as an ad hoc request. Ad hoc requests are referred to by numbers. Request 0 is either the request that is currently being entered or, if no request is being entered, the most recently entered request. Request -1 refers to the request entered before the most recent one, -2 to the one before that, and so on.</p>
<p>
You can also define the number of a temporary procedure explicitly by assigning it a negative number in the PROCEDURE command. </p>
<p>
Temporary procedures and ad hoc requests use the same numbering system. NORQS, a UTABLE parameter, determines the total number of temporary procedures and requests. </p>
<p>
A temporary procedure can contain commands and other text and need not be only a simple User Language request. </p>
===Avoiding the loss of the oldest temporary procedure===
<p>
When a new request is entered by entering either of the following commands:</p>
<p class="code">BEGIN
</p>
</p>
<p>or:</p>
<p>
<p class="code">MORE  
or:</p>
<p class="code">MORE
</p>
</p>
<p>the new request becomes the current one. The previous request, which has been assigned number 0, is now assigned the number -1; -1 becomes -2, and so on. If <var class="product">Model&nbsp;204</var> is already maintaining the maximum number of procedures or requests, the oldest is lost.</p>
<p>
<p>There are three ways to preserve the oldest request or temporary procedure before replacing it with the next oldest:</p>
the new request becomes the current one. The previous request, which has been assigned number 0, is now assigned the number -1; -1 becomes -2, and so on. If <var class="product">Model&nbsp;204</var> is already maintaining the maximum number of procedures or requests, the oldest is lost.</p>
<p>
There are three ways to preserve the oldest request or temporary procedure before replacing it with the next oldest:</p>
<ul>
<ul>
<li>Use the Editor to insert the phrases PROCEDURE procname and END PROCEDURE before and after the oldest temporary procedure. Then INCLUDE the procedure to define it as a permanent procedure.</li>
<li>Use the Editor to insert the phrases <code>PROCEDURE <i>procname</i></code> and <code>END PROCEDURE</code> before and after the oldest temporary procedure. Then INCLUDE the procedure to define it as a permanent procedure.</li>
</li>
<li>Redefine the oldest as a permanent procedure with an EDIT command. For example:</li>
<li>Redefine the oldest as a permanent procedure with an EDIT command. For example:
<p class="code">EDIT -4, NEWPROC  
<p class="code">EDIT -4, NEWPROC
</p></li>
</p></li>
<li>Use the EDIT command to store the oldest as a more recent temporary procedure. For example:</li>
 
<p class="code">EDIT -4, -2  
<li>Use the EDIT command to store the oldest as a more recent temporary procedure. For example:
<p class="code">EDIT -4, -2
</p>
</p>
<p>in which case the old temporary procedure (-2) is deleted. </p>
<p>
in which case the old temporary procedure (-2) is deleted. </p>
</li>
</li>
</ul>
</ul>
====Running a temporary procedure====
<p>Permanent and temporary procedures are retrieved and executed with the INCLUDE command. For temporary procedures, INCLUDE has the form:</p>
===Running a temporary procedure===
<p class="code">INCLUDE n  
<p>
Permanent and temporary procedures are retrieved and executed with the INCLUDE command. For temporary procedures, INCLUDE has the form:</p>
<p class="syntax">INCLUDE <span class="term">n</span>
</p>
</p>
<p>where n is zero or a negative number. </p>
<p>
<p>A temporary procedure is included in the same way that a permanent procedure is: <var class="product">Model&nbsp;204</var> executes each system control command in the procedure. In other respects, the way <var class="product">Model&nbsp;204</var> responds depends upon the characteristics of the procedure:</p>
where <var class="term">n</var> is zero or a negative number. </p>
<p>
A temporary procedure is included in the same way that a permanent procedure is: <var class="product">Model&nbsp;204</var> executes each system control command in the procedure. In other respects, the way <var class="product">Model&nbsp;204</var> responds depends upon the characteristics of the procedure:</p>
<ul>
<ul>
<li>If the procedure contains one or more User Language requests, <var class="product">Model&nbsp;204</var> compiles and executes these requests.</li>
<li>If the procedure contains one or more User Language requests, <var class="product">Model&nbsp;204</var> compiles and executes these requests.</li>
Line 536: Line 731:
</li>
</li>
</ul>
</ul>
===Dummy strings in procedures===
<p>Whenever a procedure is included, it is interpreted line by line from storage exactly as it was input at definition time. However, a special facility of the User Language, dummy strings, allows you to temporarily change certain terms and statements within the procedure each time it is included. When the procedure is defined, items to be replaced at INCLUDE time should be represented by dummy strings.    </p>
==Dummy strings in procedures==
<p>By responding to a prompt on the terminal, you can enter the replacement values to be inserted in the procedure. As described on [[#Entering dummy string responses in commands|Entering dummy string responses in commands]], you can also enter these replacement values as part of the command (IF or INCLUDE) or INCLUDE statement with which you initiate the execution of the procedure. </p>
<p>
<p>See the following four sections, which describe: </p>
Whenever a procedure is included, it is interpreted line by line from storage exactly as it was input at definition time. However, a special facility of the User Language, dummy strings, allows you to temporarily change certain terms and statements within the procedure each time it is included. When the procedure is defined, items to be replaced at INCLUDE time should be represented by dummy strings.    </p>
<p>
By responding to a prompt on the terminal, you can enter the replacement values to be inserted in the procedure. As described on [[#Entering dummy string responses in commands|Entering dummy string responses in commands]], you can also enter these replacement values as part of the command (IF or INCLUDE) or INCLUDE statement with which you initiate the execution of the procedure. </p>
<p>
See the following four sections, which describe: </p>
<ul>
<ul>
<li>[[#Entering dummy string responses in commands|Entering dummy string responses in commands]]</li>
<li>[[#Entering dummy string responses in commands|Entering dummy string responses in commands]]</li>
Line 546: Line 745:
<li>[[#Repeating dummy strings|Repeating dummy strings]]</li>
<li>[[#Repeating dummy strings|Repeating dummy strings]]</li>
</ul>
</ul>
====$READ function====
<p>In many cases, the use of the dummy string feature can be replaced by the $READ function. For more information, refer to [[$READ#$READ|$READ]].      </p>
===$READ function===
<b>Syntax</b>
<p>
<p>Dummy strings consist of one of these punctuation mark pairs, followed immediately by the character string to be displayed on the terminal as a prompt:</p>
In many cases, the use of the dummy string feature can be replaced by the $READ function. For more information, refer to [[$READ#$READ|$READ]].      </p>
====Syntax====
<p>
Dummy strings consist of one of these punctuation mark pairs, followed immediately by the character string to be displayed on the terminal as a prompt:</p>
<ul>
<ul>
<li>Two question marks (??)</li>
<li>Two question marks (??)</li>
<p>Responses to these dummy strings are expected at the I/O level immediately above the level of the dummy string. Thus, if a procedure is nested, a dummy string response to a prompt in the nested procedure would be expected in the procedure that includes the nested procedure.</p>
<p>
Responses to these dummy strings are expected at the I/O level immediately above the level of the dummy string. Thus, if a procedure is nested, a dummy string response to a prompt in the nested procedure would be expected in the procedure that includes the nested procedure.</p>
</li>
</li>
<li>A question mark and a dollar sign (?$)</li>
<li>A question mark and a dollar sign (?$)</li>
<p>These dummy strings allow you to enter responses from the terminal, regardless of the level of procedure nesting.</p>
<p>
These dummy strings allow you to enter responses from the terminal, regardless of the level of procedure nesting.</p>
</li>
</li>
<li>A question mark and an ampersand (?&amp;)    </li>
<li>A question mark and an ampersand (?&amp;)    </li>
<p>These dummy strings allow <var class="product">Model&nbsp;204</var> to obtain responses from the global variable table.    </p>
<p>
These dummy strings allow <var class="product">Model&nbsp;204</var> to obtain responses from the global variable table.    </p>
</li>
</li>
</ul>
</ul>
<p>The prompt string can contain any of the characters A-Z, 0-9, or period (.). </p>
<p>
<p>When dummy strings are displayed on the terminal, they always appear with two question marks, even if they are ?$ or ?&amp; dummy strings. When the procedure is included, each dummy string is printed on the terminal and the user enters substitute data for it. </p>
The prompt string can contain any of the characters A-Z, 0-9, or period (.). </p>
<p>Responses to all three types of dummy strings can also be specified in the INCLUDE command, as described on [[#Entering dummy string responses in commands|Entering dummy string responses in commands]]. <var class="product">Model&nbsp;204</var> looks for a response in the command before prompting you for a response.</p>
<p>
<p>There is no limit to the number of dummy strings that can appear in a procedure.</p>
When dummy strings are displayed on the terminal, they always appear with two question marks, even if they are ?$ or ?&amp; dummy strings. When the procedure is included, each dummy string is printed on the terminal and the user enters substitute data for it. </p>
====Producing a report on any field====
<p>
<p>The following is an example of a procedure which can be used, without modifying the code, to produce a report on any agent:</p>
Responses to all three types of dummy strings can also be specified in the INCLUDE command, as described on [[#Entering dummy string responses in commands|Entering dummy string responses in commands]]. <var class="product">Model&nbsp;204</var> looks for a response in the command before prompting you for a response.</p>
<p>
There is no limit to the number of dummy strings that can appear in a procedure.</p>
===Producing a report on any field===
<p>
The following is an example of a procedure which can be used, without modifying the code, to produce a report on any agent:</p>
<p class="code">PROCEDURE AGENT.DATA
<p class="code">PROCEDURE AGENT.DATA
BEGIN
BEGIN
Line 576: Line 788:
           END FOR
           END FOR
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>When procedure AGENT.DATA is included, the following prompt appears on the terminal:</p>
<p>
<p class="code">??ENTER.AGENT  
When procedure AGENT.DATA is included, the following prompt appears on the terminal:</p>
<p class="code">??ENTER.AGENT
</p>
</p>
<p>The user then enters the particular agent to be used as the selection criteria for this request (for example, CASOLI). <var class="product">Model&nbsp;204</var> replaces the dummy string with the actual value, CASOLI, and compiles the line as if it had read AGENT = CASOLI.</p>
<p>
====Defining and including a procedure====
The user then enters the particular agent to be used as the selection criteria for this request (for example, CASOLI). <var class="product">Model&nbsp;204</var> replaces the dummy string with the actual value, CASOLI, and compiles the line as if it had read AGENT = CASOLI.</p>
<p>This example illustrates a procedure definition and the subsequent prompts and replies that occur when the procedure is included.</p>
===Defining and including a procedure===
<p>
This example illustrates a procedure definition and the subsequent prompts and replies that occur when the procedure is included.</p>
<p class="code">PROCEDURE CLIENTRPT
<p class="code">PROCEDURE CLIENTRPT
BEGIN
BEGIN
Line 597: Line 813:
END
END
END PROCEDURE
END PROCEDURE
 
INCLUDE CLIENTRPT
INCLUDE CLIENTRPT
??SELECTION  
??SELECTION
STATE = NEW YORK  
STATE = NEW YORK
??KEY  
??KEY
POLICY NO  
POLICY NO
??HEADING1  
??HEADING1
'NEW YORK DRIVERS' AT COLUMN 10  
'NEW YORK DRIVERS' AT COLUMN 10
??REPORT.DATA  
??REPORT.DATA
POLICY NO WITH FULLNAME AT COLUMN 10  
POLICY NO WITH FULLNAME AT COLUMN 10
</p>
</p>
<p>The procedure actually compiles as:</p>
<p>
The procedure actually compiles as:</p>
<p class="code">BEGIN
<p class="code">BEGIN
SELECT.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
SELECT.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
Line 620: Line 837:
                   WITH FULLNAME AT COLUMN 10
                   WITH FULLNAME AT COLUMN 10
             END FOR
             END FOR
END  
END
</p>
</p>
<p>The compiler expects one physical line of input for each dummy string. </p>
<p>
====Using dummy strings to create a group====
The compiler expects one physical line of input for each dummy string. </p>
<p>You want to specify the names of the files that make up a temporary group and the parameter values required for the CREATE command. An example of a procedure that does this using dummy strings follows:</p>
<p class="code">PROCEDURE TAXGROUP  
===Using dummy strings to create a group===
<p>
You want to specify the names of the files that make up a temporary group and the parameter values required for the CREATE command. An example of a procedure that does this using dummy strings follows:</p>
<p class="code">PROCEDURE TAXGROUP
CREATE TEMP GROUP TAXES FROM ??ENTER.FILE.NAMES
CREATE TEMP GROUP TAXES FROM ??ENTER.FILE.NAMES
PARAMETER ??ENTER.PARAMETERS.AND.VALUES
PARAMETER ??ENTER.PARAMETERS.AND.VALUES
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>When the TAXGROUP procedure is included, the first of two prompts is displayed on your terminal:</p>
<p>
<p class="code">??ENTER.FILE.NAMES  
When the TAXGROUP procedure is included, the first of two prompts is displayed on your terminal:</p>
<p class="code">??ENTER.FILE.NAMES
</p>
</p>
<p>In response, you enter the particular file names that are to make up the TAX group. For example:</p>
<p>
<p class="code">TAX, TABLE2, BENEFITS  
In response, you enter the particular file names that are to make up the TAX group. For example:</p>
<p class="code">TAX, TABLE2, BENEFITS
</p>
</p>
<p><var class="product">Model&nbsp;204</var> replaces the dummy string with this list of file names and then displays the second prompt:</p>
<p>
<p class="code">??ENTER.PARAMETERS.AND.VALUES  
<var class="product">Model&nbsp;204</var> replaces the dummy string with this list of file names and then displays the second prompt:</p>
<p class="code">??ENTER.PARAMETERS.AND.VALUES
</p>
</p>
<p>In response, you enter:</p>
<p>
<p class="code">PROCFILE=TAX  
In response, you enter:</p>
<p class="code">PROCFILE=TAX
</p>
</p>
<p><var class="product">Model&nbsp;204</var> replaces the second dummy string with parameter settings and executes the CREATE command.</p>
<p>
====Using a dummy string to capture input====
<var class="product">Model&nbsp;204</var> replaces the second dummy string with parameter settings and executes the CREATE command.</p>
<p>If the user wishes to enter more than one line of substitution for a dummy string the original procedure should contain a separate dummy string for each expected line of input:</p>
===Using a dummy string to capture input===
<p>
If the user wishes to enter more than one line of substitution for a dummy string the original procedure should contain a separate dummy string for each expected line of input:</p>
<p class="code">PROCEDURE EXAMP
<p class="code">PROCEDURE EXAMP
BEGIN
BEGIN
Line 652: Line 879:
??TEXT.END'
??TEXT.END'
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>Although the user is prompted three times, each line acts as a continuation of the one preceding, and all are concatenated with a single space before each continuation to form the value of the field TEXT. If all desired data has been entered before the prompts end, the user can respond to additional prompts with a carriage return.</p>
<p>
===Entering dummy string responses in commands===
Although the user is prompted three times, each line acts as a continuation of the one preceding, and all are concatenated with a single space before each continuation to form the value of the field TEXT. If all desired data has been entered before the prompts end, the user can respond to additional prompts with a carriage return.</p>
<p>The value of a ?? or ?$ dummy string can alternatively be entered as part of the INCLUDE or IF command or in an INCLUDE statement. <var class="product">Model&nbsp;204</var> accepts the values passed by the INCLUDE or IF as replacements for the dummy strings in the procedure. The dummy string responses are not prompted for if they are entered in advance on the INCLUDE line.</p>
<p>Referring to the example, [[#Producing a report on any field|Producing a report on any field]], you could execute the AGENT.DATA procedure by entering:  </p>
==Entering dummy string responses in commands==
<p class="code">INCLUDE AGENT.DATA CASOLI  
<p>
The value of a ?? or ?$ dummy string can alternatively be entered as part of the INCLUDE or IF command or in an INCLUDE statement. <var class="product">Model&nbsp;204</var> accepts the values passed by the INCLUDE or IF as replacements for the dummy strings in the procedure. The dummy string responses are not prompted for if they are entered in advance on the INCLUDE line.</p>
<p>
Referring to the example, [[#Producing a report on any field|Producing a report on any field]], you could execute the AGENT.DATA procedure by entering:  </p>
<p class="code">INCLUDE AGENT.DATA CASOLI
</p>
</p>
<p>instead of waiting for <var class="product">Model&nbsp;204</var> to prompt for the agent by displaying:</p>
<p>
<p class="code">??ENTER.AGENT  
instead of waiting for <var class="product">Model&nbsp;204</var> to prompt for the agent by displaying:</p>
<p class="code">??ENTER.AGENT
</p>
</p>
====Delimiter characters for multiple responses====
<p>Any number of responses can be specified on the INCLUDE line. Responses must be separated by one of the following delimiters. The character immediately following the name is used as the delimiter.</p>
===Delimiter characters for multiple responses===
<p>
Any number of responses can be specified on the INCLUDE line. Responses must be separated by one of the following delimiters. The character immediately following the name is used as the delimiter.</p>
<ul>
<ul>
<li>Blank</li>
<li>Blank</li>
Line 677: Line 911:
</li>
</li>
</ul>
</ul>
<p>The list of responses can be continued using either a trailing hyphen or the continuation column.</p>
<p>
<p>To execute the TAXGROUP procedure (from the example [[#Using dummy strings to create a group|Using dummy strings to create a group]]) with a single command, you can enter:</p>
The list of responses can be continued using either a trailing hyphen or the continuation column.</p>
<p>
To execute the TAXGROUP procedure (from the example [[#Using dummy strings to create a group|Using dummy strings to create a group]]) with a single command, you can enter:</p>
<p class="code">INCLUDE TAXGROUP TAX,TABLE2,BENEFITS PROCFILE=TAX
<p class="code">INCLUDE TAXGROUP TAX,TABLE2,BENEFITS PROCFILE=TAX
</p>
</p>
<p>instead of waiting for the <var class="product">Model&nbsp;204</var> prompts for the file names and parameters:</p>
<p>
instead of waiting for the <var class="product">Model&nbsp;204</var> prompts for the file names and parameters:</p>
<p class="code">??ENTER.FILE.NAMES
<p class="code">??ENTER.FILE.NAMES
??ENTER.PARAMETERS.AND.VALUES  
??ENTER.PARAMETERS.AND.VALUES
</p>
</p>
<p>The space between TAXGROUP and TAX is the delimiter; the commas and equal sign are actually part of the string (the value of the variable). <var class="product">Model&nbsp;204</var> replaces the dummy strings in the procedure with the following values:</p>
<p>
<p class="code">TAX,TABLE2,BENEFITS  
The space between TAXGROUP and TAX is the delimiter; the commas and equal sign are actually part of the string (the value of the variable). <var class="product">Model&nbsp;204</var> replaces the dummy strings in the procedure with the following values:</p>
PROCFILE=TAX
<p class="code">TAX,TABLE2,BENEFITS
PROCFILE=TAX
</p>
</p>
====Mixing dummy string and $READ responses in the INCLUDE or IF line====
<p>Responses to both dummy strings and the $READ function can be specified in the INCLUDE or IF line. Dummy string responses must appear first, followed by $READ responses. </p>
===Mixing dummy string and $READ responses in the INCLUDE or IF line===
<p>If any $READ responses are included in the list, the list also must include a response for each dummy string that is encountered before the first $READ is executed.      </p>
<p>
<p>As dummy strings and $READs are encountered in the procedure that is being included, entries are retrieved from the list specified in the INCLUDE or IF line. If there are more dummy strings and $READs than responses in the list, <var class="product">Model&nbsp;204</var> retrieves entries from the list and then prompts for the remaining dummy strings and $READs.</p>
Responses to both dummy strings and the $READ function can be specified in the INCLUDE or IF line. Dummy string responses must appear first, followed by $READ responses. </p>
<b>Example</b>
<p>
<p>This procedure contains one dummy string and one $READ function.</p>
If any $READ responses are included in the list, the list also must include a response for each dummy string that is encountered before the first $READ is executed.      </p>
<p>
As dummy strings and $READs are encountered in the procedure that is being included, entries are retrieved from the list specified in the INCLUDE or IF line. If there are more dummy strings and $READs than responses in the list, <var class="product">Model&nbsp;204</var> retrieves entries from the list and then prompts for the remaining dummy strings and $READs.</p>
====Example====
<p>
This procedure contains one dummy string and one $READ function.</p>
<p class="code">PROCEDURE DUMMY
<p class="code">PROCEDURE DUMMY
BEGIN
BEGIN
Line 700: Line 944:
       PRINT %A AND '??FIRST.PROMPT'
       PRINT %A AND '??FIRST.PROMPT'
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>The user can run this procedure by entering:</p>
<p>
<p class="code">INCLUDE DUMMY,ONE,TWO  
The user can run this procedure by entering:</p>
<p class="code">INCLUDE DUMMY,ONE,TWO
</p>
</p>
<p>The resulting output would be:</p>
<p>
<p class="code">TWO ONE  
The resulting output would be:</p>
<p class="code">TWO ONE
</p>
</p>
====Using *CANCEL to return to command level====
<p>If the user responds to a dummy string prompt with *CANCEL, <var class="product">Model&nbsp;204</var> terminates compilation, ends all procedures, and returns control to the command level at the user's terminal.    </p>
===Using *CANCEL to return to command level===
===Specifying dummy strings in nested procedures===
<p>
<p>Dummy string substitution lines are entered from the level at which the procedure was included. </p>
If the user responds to a dummy string prompt with *CANCEL, <var class="product">Model&nbsp;204</var> terminates compilation, ends all procedures, and returns control to the command level at the user's terminal.    </p>
<p>If INCLUDE is entered at the terminal by the user, the input line substitution is requested from the terminal or is taken from responses entered as part of the terminal INCLUDE line. </p>
<p>Suppose, however, the user includes procedure TEST, and procedure TEST in turn includes procedure REPT. If procedure REPT contains dummy strings, <var class="product">Model&nbsp;204</var> expects the substitution lines to be provided from within procedure TEST. </p>
==Specifying dummy strings in nested procedures==
<p>Substitution lines, one per dummy string, should follow immediately after the INCLUDE REPT statement in the definition of procedure TEST.</p>
<p>
<b>Example</b>
Dummy string substitution lines are entered from the level at which the procedure was included. </p>
<p>
If INCLUDE is entered at the terminal by the user, the input line substitution is requested from the terminal or is taken from responses entered as part of the terminal INCLUDE line. </p>
<p>
Suppose, however, the user includes procedure TEST, and procedure TEST in turn includes procedure REPT. If procedure REPT contains dummy strings, <var class="product">Model&nbsp;204</var> expects the substitution lines to be provided from within procedure TEST. </p>
<p>
Substitution lines, one per dummy string, should follow immediately after the INCLUDE REPT statement in the definition of procedure TEST.</p>
====Example====
<p class="code">PROCEDURE TEST
<p class="code">PROCEDURE TEST
BEGIN
BEGIN
Line 726: Line 980:
END
END
END PROCEDURE
END PROCEDURE
 
PROCEDURE REPT
PROCEDURE REPT
         FOR EACH RECORD IN POL.NO
         FOR EACH RECORD IN POL.NO
Line 734: Line 988:
             PRINT ??REPORT.2
             PRINT ??REPORT.2
         END FOR
         END FOR
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>Assume that the user includes the procedure TEST from his/her terminal. The user is prompted with ??ENTER.POLICY.NO and enters a valid policy number. When procedure REPT is included from procedure TEST, the user is not prompted. <var class="product">Model&nbsp;204</var> automatically substitutes FULLNAME AND DRIVER ID for ??REPORT.1 and POLICY NO AND STATE for ??REPORT.2.</p>
<p>
Assume that the user includes the procedure TEST from his/her terminal. The user is prompted with ??ENTER.POLICY.NO and enters a valid policy number. When procedure REPT is included from procedure TEST, the user is not prompted. <var class="product">Model&nbsp;204</var> automatically substitutes FULLNAME AND DRIVER ID for ??REPORT.1 and POLICY NO AND STATE for ??REPORT.2.</p>
====User parameters====
====User parameters====
<p>Certain user parameters control prompting and line substitution for dummy strings. Refer to the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual for information about those parameters and procedure nesting.</p>
<p>
====Specifying dummy string responses in the INCLUDE command====
The <var>[[SUB parameter|SUB]]</var>, <var>[[PROMPT parameter|PROMPT]]</var>, and <var>[[LSECHO parameter|LSECHO]]</var> user parameters control prompting and line substitution for dummy strings.
<p>To specify dummy string responses in the INCLUDE command instead, the user can issue:</p>
<p class="code">INCLUDE TEST, 100340  
===Specifying dummy string responses in the INCLUDE command===
<p>
To specify dummy string responses in the INCLUDE command instead, the user can issue:</p>
<p class="code">INCLUDE TEST, 100340
</p>
</p>
<p>Therefore, the INCL.REPT statement in procedure TEST could be written:</p>
<p>
<p class="code">INCL.RPT:INCLUDE REPT,FULLNAME AND DRIVER ID,POLICY NO AND STATE
Therefore, the INCL.REPT statement in procedure TEST could be written:</p>
   
<p class="code">INCL.RPT:INCLUDE REPT,FULLNAME AND DRIVER ID,POLICY NO AND STATE  
</p>
</p>
===Using ?$ and ?& dummy strings===
====Using ?$ dummy strings====
==Using ?$ and ?& dummy strings==
<b>Description</b>
<p>The user controls the level at which substitutions are entered by prefixing the dummy strings with ?$ instead of ??. The ?$ causes <var class="product">Model&nbsp;204</var> to expect line substitutions for those dummy strings from the user's terminal, no matter how deeply the procedure containing the dummy string is nested.</p>
===Using ?$ dummy strings===
<b>Example</b>
<p>For example, suppose the previously defined procedure REPT contained:</p>
====Description====
<p>
The user controls the level at which substitutions are entered by prefixing the dummy strings with ?$ instead of ??. The ?$ causes <var class="product">Model&nbsp;204</var> to expect line substitutions for those dummy strings from the user's terminal, no matter how deeply the procedure containing the dummy string is nested.</p>
====Example====
<p>
For example, suppose the previously defined procedure REPT contained:</p>
<p class="code">FOR EACH RECORD IN POL.NO
<p class="code">FOR EACH RECORD IN POL.NO
   PRINT ?$REPORT.1
   PRINT ?$REPORT.1
END FOR  
END FOR
</p>
</p>
<p>Then ??REPORT.1 would appear at the terminal and the user would enter a substitution line there, and not from within procedure TEST. The dummy string response alternatively can be specified in the INCLUDE command that invokes TEST.    </p>
<p>
====Using ?& dummy strings====
Then ??REPORT.1 would appear at the terminal and the user would enter a substitution line there, and not from within procedure TEST. The dummy string response alternatively can be specified in the INCLUDE command that invokes TEST.    </p>
<b>Description</b>
<p>A user can read dummy string responses from the global variable table, GTBL, by prefixing them with ?&amp;. Global variables are discussed in [[Global features]].      </p>
===Using ?& dummy strings===
<p>This facility allows systems or requests to communicate with each other. In the dummy string specification:</p>
<p class="code">?&amp;globalname  
====Description====
<p>
A user can read dummy string responses from the global variable table, GTBL, by prefixing them with ?&amp;. Global variables are discussed in [[Global features]].      </p>
<p>
This facility allows systems or requests to communicate with each other. In the dummy string specification:</p>
<p class="syntax">?&amp;<span class="term">globalname</span>
</p>
</p>
<p>globalname identifies the variable to be read from the global variable table. The value of the named variable is substituted for the dummy string. If the variable is not defined in the table, the variable name specified in the dummy string is displayed on the user's terminal as a prompt. The user then enters the replacement value, as shown below. The response to a ?&amp; prompt cannot be specified as an argument in an INCLUDE line as other dummy string responses can be.    </p>
<p>
<p class="note"><b>Note:</b> Do not use global variable names containing an underscore (_) in ?&amp; dummy strings. The underscore is not a valid character for dummy strings. An underscore in a ?&amp; dummy string causes the string to be truncated. For example, the ?&amp; dummy string:</p>
<var class="term">globalname</var> identifies the variable to be read from the global variable table. The value of the named variable is substituted for the dummy string. If the variable is not defined in the table, the variable name specified in the dummy string is displayed on the user's terminal as a prompt. The user then enters the replacement value, as shown below. The response to a ?&amp; prompt cannot be specified as an argument in an INCLUDE line as other dummy string responses can be.    </p>
<p><var>?&amp;TEST_GLOBAL</var></p>
 
<p>is interpreted as looking for a global variable named <var>TEST</var>.</p>
<blockquote class="note">
<b>Example</b>
<p><b>Note:</b> Do not use global variable names containing an underscore (_) in ?&amp; dummy strings. The underscore is not a valid character for dummy strings. An underscore in a ?&amp; dummy string causes the string to be truncated. For example, the ?&amp; dummy string:</p>
<p>Suppose the REPT procedure contains:</p>
<p class="code">?&amp;TEST_GLOBAL</p>
<p>
is interpreted as looking for a global variable named <var>TEST</var>.</p>
</blockquote>
====Example====
<p>
Suppose the REPT procedure contains:</p>
<p class="code">FOR EACH RECORD IN POL.NO
<p class="code">FOR EACH RECORD IN POL.NO
   PRINT ?&amp;REPORT.1
   PRINT ?&amp;REPORT.1
END FOR  
END FOR
</p>
</p>
<p>If the global variable table does not contain a value for REPORT.1, <var class="product">Model&nbsp;204</var> displays:</p>
<p>
<p class="code">??REPORT.1  
If the global variable table does not contain a value for REPORT.1, <var class="product">Model&nbsp;204</var> displays:</p>
<p class="code">??REPORT.1
</p>
</p>
<p>The user then responds with the desired value, for example:</p>
<p>
<p class="code">FULLNAME AND DRIVER ID    
The user then responds with the desired value, for example:</p>
<p class="code">FULLNAME AND DRIVER ID
</p>
</p>
===Repeating dummy strings===
<p>It often is necessary to repeat a dummy string several times within a procedure, even though only a single response is desired. </p>
==Repeating dummy strings==
<b>Example</b>
<p>
It often is necessary to repeat a dummy string several times within a procedure, even though only a single response is desired. </p>
====Example====
<p class="code">PROCEDURE SORT
<p class="code">PROCEDURE SORT
BEGIN
BEGIN
Line 792: Line 1,074:
           END FOR
           END FOR
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>When including this procedure the user is asked to supply the same fields twice. For example:</p>
<p>
<p class="code">INCLUDE SORT
When including this procedure the user is asked to supply the same fields twice. For example:</p>
??FIELDS  
<p class="code">INCLUDE SORT
AGENT AND FULLNAME  
??FIELDS
??FIELDS  
AGENT AND FULLNAME
AGENT AND FULLNAME  
??FIELDS
AGENT AND FULLNAME
</p>
</p>
====Technique 1====
<p>You can overcome the inconvenience of the user having to enter the same fields twice by using the following technique. First, the ?&amp; form of the dummy string prompt can be used by adding a brief request at the beginning of the procedure (continued on next page):</p>
===Technique 1===
<p>
You can overcome the inconvenience of the user having to enter the same fields twice by using the following technique. First, the ?&amp; form of the dummy string prompt can be used by adding a brief request at the beginning of the procedure (continued on next page):</p>
<p class="code">PROCEDURE SORT
<p class="code">PROCEDURE SORT
BEGIN
BEGIN
Line 813: Line 1,098:
BEGIN
BEGIN
   .
   .
   .  
   .
 
SORT.RECS:  SORT RECORDS IN FIND.RECS BY ?&amp;FIELDS
SORT.RECS:  SORT RECORDS IN FIND.RECS BY ?&amp;FIELDS
PRINT.FL:  FOR EACH RECORD IN SORT.RECS
PRINT.FL:  FOR EACH RECORD IN SORT.RECS
Line 820: Line 1,105:
             END FOR
             END FOR
END
END
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>The new request prompts the user for the sort criteria and includes it in a global variable, FIELDS. This is the only prompt the user sees. The global variable table now contains the variable FIELDS and its value as entered by the user. When evaluation of the second request reaches the ?&amp;FIELDS dummy string in the SORT.RECS and PRINT.FL statements, the response is taken from the value in the global variable table. No prompt appears at the user's terminal.</p>
<p>
<p>The global variable is set in a separate request, because dummy strings prompt the user at compile time. If it were in the same request, the user would be prompted, %F would be set, and the TABLE.FULL statements would be compiled but not performed until evaluation. The compiler would then reach the SORT.RECS statement. There would be no value for FIELDS in the global variable table, thus the user would receive a second prompt. The value still would not be saved, and the user would be prompted a third time in the PRINT.FL statement.</p>
The new request prompts the user for the sort criteria and includes it in a global variable, FIELDS. This is the only prompt the user sees. The global variable table now contains the variable FIELDS and its value as entered by the user. When evaluation of the second request reaches the ?&amp;FIELDS dummy string in the SORT.RECS and PRINT.FL statements, the response is taken from the value in the global variable table. No prompt appears at the user's terminal.</p>
====Technique 2====
<p>
<p>Another alternative is to edit the SORT procedure. (<var class="product">Model&nbsp;204</var> editors are discussed in the Rocket <var class="product">Model&nbsp;204</var> Editing Guide.) </p>
The global variable is set in a separate request, because dummy strings prompt the user at compile time. If it were in the same request, the user would be prompted, %F would be set, and the TABLE.FULL statements would be compiled but not performed until evaluation. The compiler would then reach the SORT.RECS statement. There would be no value for FIELDS in the global variable table, thus the user would receive a second prompt. The value still would not be saved, and the user would be prompted a third time in the PRINT.FL statement.</p>
<p>For example:</p>
===Technique 2===
<p>
Another alternative is to edit the SORT procedure. (<var class="product">Model&nbsp;204</var> editors are discussed in the <var class="book">Rocket Model&nbsp;204 Editing Guide</var>.) </p>
<p>
For example:</p>
<p class="code">PROCEDURE SORT
<p class="code">PROCEDURE SORT
EDIT SORTX, 0
EDIT SORTX, 0
Line 832: Line 1,122:
GO
GO
END PROCEDURE
END PROCEDURE
 
PROCEDURE SORTX
PROCEDURE SORTX
     .
     .
Line 844: Line 1,134:
END PROCEDURE
END PROCEDURE
</p>
</p>
<p>When procedure SORT is included, the user is asked to supply the field names only once (during the edit). The Editor inserts the field names into a copy of procedure SORTX in the appropriate places (replacing each occurrence of FIELDS). Finally, the edited copy of SORTX is saved as temporary procedure 0 and is executed.</p>
<p>
<p>This technique can, of course, be extended to handle several dummy strings at once. Another benefit is that once the dummy strings have been supplied, the user can rerun the same request without being asked for dummy strings. The user does this by keying INCLUDE 0. </p>
When procedure SORT is included, the user is asked to supply the field names only once (during the edit). The Editor inserts the field names into a copy of procedure SORTX in the appropriate places (replacing each occurrence of FIELDS). Finally, the edited copy of SORTX is saved as temporary procedure 0 and is executed.</p>
===Using Model 204 parameters to control dummy strings===
<p>
<p>Three parameters control the use of dummy strings:</p>
This technique can, of course, be extended to handle several dummy strings at once. Another benefit is that once the dummy strings have been supplied, the user can rerun the same request without being asked for dummy strings. The user does this by keying INCLUDE 0. </p>
==Using Model 204 parameters to control dummy strings==
<p>
Three parameters control the use of dummy strings:</p>
<ul>
<ul>
<li>SUB determines whether, and at what I/O levels, dummy string substitution takes place.</li>
<li>SUB determines whether, and at what I/O levels, dummy string substitution takes place.</li>
Line 853: Line 1,146:
<li>LSECHO governs the echoing of lines in which dummy string substitution takes place. </li>
<li>LSECHO governs the echoing of lines in which dummy string substitution takes place. </li>
</ul>
</ul>
<p>Individual parameters are discussed in detail in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual.    </p>
====Input/Output levels direct dummy string replacement====
===Input/Output levels direct dummy string replacement===
<p>An explanation of input/output (I/O) levels helps to distinguish between types of dummy strings and to understand the details of setting SUB and PROMPT. Input/output for the normal device, your terminal, usually has an I/O level of zero. Each time an INCLUDE is encountered, the I/O level is increased by one, up to a maximum of five. At the end of the included procedure, the I/O level is decreased by 1.</p>
<p>
<p>When a ?? dummy string is found in the input stream, at any I/O level, <var class="product">Model&nbsp;204</var> gets the replacement for it from the current I/O level minus one. The replacement for a ?$ dummy string always comes from I/O level 0 (the terminal). ?&amp; responses also come from level zero, if the prompt string cannot be found in the global variable table.</p>
An explanation of input/output (I/O) levels helps to distinguish between types of dummy strings and to understand the details of setting SUB and PROMPT. Input/output for the normal device, your terminal, usually has an I/O level of zero. Each time an INCLUDE is encountered, the I/O level is increased by one, up to a maximum of five. At the end of the included procedure, the I/O level is decreased by 1.</p>
====Using PROMPT to control dummy string substitution====
<p>
<p>The default setting (9) for the PROMPT parameter implies that dummy string, $READ, and $ENTER prompting occurs at the terminal. PROMPT settings are described in detail in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual. Even if you set PROMPT= to a value to suppress the display of dummy string substitution at a particular I/O level, the system still makes the substitution if the SUB parameter is properly set and a dummy string is present.</p>
When a ?? dummy string is found in the input stream, at any I/O level, <var class="product">Model&nbsp;204</var> gets the replacement for it from the current I/O level minus one. The replacement for a ?$ dummy string always comes from I/O level 0 (the terminal). ?&amp; responses also come from level zero, if the prompt string cannot be found in the global variable table.</p>
====Example and discussion featuring PROMPT====
<p>Two procedures are defined:</p>
===Using PROMPT to control dummy string substitution===
<p>
The default setting (9) for the <var>[[PROMPT parameter|PROMPT]]</var> parameter implies that dummy string, $READ, and $ENTER prompting occurs at the terminal.
Even if you set PROMPT= to a value to suppress the display of dummy string substitution at a particular I/O level, the system still makes the substitution if the SUB parameter is properly set and a dummy string is present.</p>
===Example and discussion featuring PROMPT===
<p>
Two procedures are defined:</p>
<p class="code">PROCEDURE INNER
<p class="code">PROCEDURE INNER
RESET PROMPT = 5
RESET PROMPT = 5
Line 867: Line 1,167:
END
END
END PROCEDURE
END PROCEDURE
 
PROCEDURE OUTER
PROCEDURE OUTER
INCLUDE INNER
INCLUDE INNER
??DUMMY2
??DUMMY2
END PROCEDURE  
END PROCEDURE
</p>
</p>
<p>If you execute the procedure INNER, the following sequence occurs:</p>
<p>
If you execute the procedure INNER, the following sequence occurs:</p>
<p class="code">INCLUDE INNER
<p class="code">INCLUDE INNER
 
??DUMMY1    Prompt for substitution.
??DUMMY1    Prompt for substitution.
 
YELLOW      Substitute.  
YELLOW      Substitute.
 
YELLOW      Result of PRINT statement.  
YELLOW      Result of PRINT statement.
</p>
</p>
<p>If you execute the procedure OUTER, this sequence occurs:</p>
<p>
If you execute the procedure OUTER, this sequence occurs:</p>
<p class="code">INCLUDE OUTER
<p class="code">INCLUDE OUTER
 
??DUMMY1
??DUMMY1
??DUMMY2
??DUMMY2  
 
   
   
 
YELLOW
YELLOW  
</p>
</p>
<p>In this case, the prompt ??DUMMY2 becomes itself the response that is taken for the prompt ??DUMMY1; but because it is also a dummy string, the substitution is not actually made until you enter YELLOW. This result occurs for the following reasons: </p>
<p>
In this case, the prompt ??DUMMY2 becomes itself the response that is taken for the prompt ??DUMMY1; but because it is also a dummy string, the substitution is not actually made until you enter YELLOW. This result occurs for the following reasons: </p>
<ul>
<ul>
<li>The line INCLUDE OUTER is entered at I/O level 0. </li>
<li>The line INCLUDE OUTER is entered at I/O level 0. </li>
</li>
<li>Procedure OUTER at I/O level 1 includes procedure INNER at I/O level 2. </li>
<li>Procedure OUTER at I/O level 1 includes procedure INNER at I/O level 2. </li>
</li>
<li><var class="product">Model&nbsp;204</var> expects to get the substitute for ??DUMMY1 from I/O level 1, procedure OUTER. (When a ?? dummy string is found in the input stream, at any I/O level, <var class="product">Model&nbsp;204</var> gets the replacement for it from the current I/O level minus 1.) </li>
<li><var class="product">Model&nbsp;204</var> expects to get the substitute for ??DUMMY1 from I/O level 1, procedure OUTER. (When a ?? dummy string is found in the input stream, at any I/O level, <var class="product">Model&nbsp;204</var> gets the replacement for it from the current I/O level minus 1.) </li>
</li>
<li>??DUMMY2 comes from level 0; the replacement for ??DUMMY2, YELLOW, becomes the value in procedure OUTER that is replaced for ??DUMMY1 and printed by procedure INNER. </li>
<li>??DUMMY2 comes from level 0; the replacement for ??DUMMY2, YELLOW, becomes the value in procedure OUTER that is replaced for ??DUMMY1 and printed by procedure INNER. </li>
</li>
<li>The prompt ??DUMMY1 is displayed because the PROMPT setting is 5 (the sum of options 4 and 1), which directs the display of the prompt if its replacement is expected from a procedure. (See the description of PROMPT in the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference Manual for more information about these settings.) Had PROMPT been set to 1, only ??DUMMY2 would have been displayed. </li>
<li>The prompt ??DUMMY1 is displayed because the PROMPT setting is 5 (the sum of options 4 and 1), which directs the display of the prompt if its replacement is expected from a procedure.
Had PROMPT been set to 1, only ??DUMMY2 would have been displayed.
</li>
</li>
</ul>
</ul>
====Using SUB to control dummy string substitution====
<p>The SUB parameter default setting is 4, which makes dummy string substitutions in lines from procedures (I/O levels greater than 0), but not from the terminal. If you can enter a dummy string as part of a procedure definition, no substitution is requested until you include the procedure.</p>
===Using SUB to control dummy string substitution===
<p>When SUB = 1 (substitution in lines from the terminal) or SUB = 5, the system takes special action when a request is entered. If a dummy string is entered as part of the request, <var class="product">Model&nbsp;204</var> drops from I/O level 0 to I/O level -1, and immediately requests the substitute for the dummy string. After the END statement is entered, the request is run using the substituted string. However, the stored temporary procedure retains the original dummy string. </p>
<p>
<b>Example</b>
The SUB parameter default setting is 4, which makes dummy string substitutions in lines from procedures (I/O levels greater than 0), but not from the terminal. If you can enter a dummy string as part of a procedure definition, no substitution is requested until you include the procedure.</p>
<p>Suppose you enter and run this short request:</p>
<p>
When SUB = 1 (substitution in lines from the terminal) or SUB = 5, the system takes special action when a request is entered. If a dummy string is entered as part of the request, <var class="product">Model&nbsp;204</var> drops from I/O level 0 to I/O level -1, and immediately requests the substitute for the dummy string. After the END statement is entered, the request is run using the substituted string. However, the stored temporary procedure retains the original dummy string. </p>
====Example====
<p>
Suppose you enter and run this short request:</p>
<p class="code">RESET SUB=5, PROMPT=5, LSECHO=5
<p class="code">RESET SUB=5, PROMPT=5, LSECHO=5
 
SUB    X'05'  SUBSTITUTION CONTROL
SUB    X'05'  SUBSTITUTION CONTROL
PROMPT  X'05'  PROMPT CONTROL
PROMPT  X'05'  PROMPT CONTROL
LSECHO  X'05'  LINE SUBSTITUTION ECHO
LSECHO  X'05'  LINE SUBSTITUTION ECHO
 
BEGIN  
BEGIN
LOOK:  FIND ALL RECORDS FOR WHICH
LOOK:  FIND ALL RECORDS FOR WHICH
             ICE CREAM = ??FLAVOR  
             ICE CREAM = ??FLAVOR
 
??FLAVOR
??FLAVOR
 
CHOCOLATE  
CHOCOLATE
 
ICE CREAM = CHOCOLATE  
ICE CREAM = CHOCOLATE
 
CTR:    COUNT RECORDS IN LOOK  
CTR:    COUNT RECORDS IN LOOK
PTR:    PRINT COUNT IN CTR
PTR:    PRINT COUNT IN CTR
END  
END
 
24  
24
</p>
</p>
<p>You reply <var>CHOCOLATE</var> to the prompt ??FLAVOR. <var class="product">Model&nbsp;204</var> then echoes (because LSECHO=5) <var>ICE CREAM = CHOCOLATE,</var> indicating that the substitution took place.</p>
<p>
<p>Because SUB=5, <var>??FLAVOR</var> and not <var>CHOCOLATE</var> is retained when the request is saved as temporary procedure 0. You can easily execute the request again (since it is saved as temporary procedure 0) and substitute a different flavor: </p>
You reply <var>CHOCOLATE</var> to the prompt ??FLAVOR. <var class="product">Model&nbsp;204</var> then echoes (because LSECHO=5) <var>ICE CREAM = CHOCOLATE,</var> indicating that the substitution took place.</p>
<p>
Because SUB=5,
<var>??FLAVOR</var> and not <var>CHOCOLATE</var> is retained when the request is saved as temporary procedure 0. You can easily execute the request again (since it is saved as temporary procedure 0) and substitute a different flavor: </p>
<p class="code">INCLUDE 0
<p class="code">INCLUDE 0
??FLAVOR
??FLAVOR
VANILLA
VANILLA
ICE CREAM = VANILLA
ICE CREAM = VANILLA
<var>32</var>      
<var>32</var>
</p>
</p>
[[Category:SOUL]]
[[Category:SOUL]]

Revision as of 17:47, 14 January 2014

Overview

A procedure is a sequence of input lines that can be named and saved for later use. A procedure might contain all of the lines from a User Language request that you intend to execute frequently, such as a lengthy formatted report that is run weekly. However, a procedure is not limited to a single request. It can also contain several requests, a partial request, system commands, or any combination of commands and User Language statements. A procedure can even contain text that is never executed, such as program documentation or messages to other users.

Two types of procedures

In Model 204, there are two types of procedures:

Type Description
Permanent Stored in a Model 204 file until they are deleted or redefined or until the file in which they are stored is reinitialized.
Temporary Saved in the system scratch file CCATEMP during the current terminal session and deleted when the user logs out.

Procedure storage compared to request storage

Model 204 treats procedures and requests differently. Once a permanent procedure has been stored, Model 204 saves the procedure until it is deleted or redefined, or until the file with which the procedure is associated is reinitialized.

A User Language request, on the other hand, is temporary. (A request can be defined as any set of User Language statements which follows a BEGIN or MORE command and precedes an END statement.) A number of your most recent ad hoc requests (those newly entered at the terminal) are saved automatically as temporary procedures by Model 204 as long as you remain logged in. Unlike permanent procedures, however, these temporary procedures are deleted by Model 204 when you log out. The number of temporary procedures which Model 204 saves is determined by the NORQS parameter, which has a default value of 5.

Unconditional and conditional inclusion of procedures

Use the INCLUDE command or statement to unconditionally include procedures. You can also include procedures conditionally, using an IF statement.

Nested procedures

Procedures can themselves contain INCLUDE commands or statements, creating nested procedures. You can nest procedures up to four levels deep. Thus procedure A can include procedure B; procedure B can include procedure C; procedure C can include procedure D; and procedure D can include procedure E; but procedure E cannot include other procedures. See Executing and defining procedures within procedures a detailed discussion of procedure nesting.

Dummy strings

Dummy strings allow you to temporarily change certain statements within a procedure each time it is included.

Opening non-Model 204 data sets from within procedures

If a User Language procedure attempts to open an already open non-Model 204 data set at evaluation time, Model 204 softly restarts the user with the following counting error message:

M204.2153 DATASET name IS ALREADY OPEN

Procedure commands

The system control commands commonly used with procedures are summarized in Procedure commands. For more information on these commands, refer to their individual descriptions accessed via List of Model 204 parameters.

Procedure control commands
Command Description
DELETE Deletes a procedure.
DISPLAY Print a procedure to a terminal.
EDIT Edits a procedure.
IF Tests a condition, allows a procedure to be executed conditionally.
INCLUDE Executes a procedure; procedures can be nested.
PROCEDURE Creates a procedure and assigns it a name.

Creating a procedure

You can use the PROCEDURE command or the Full Screen Editor to define a procedure. This section discusses creating procedures primarily by means of the PROCEDURE command process. This section also includes an example of how to create a procedure and a discussion of the storage of a procedure.

PROCEDURE command process

You can use the PROCEDURE command to create a new procedure or to replace an existing procedure. The PROCEDURE command process has three steps:

  1. Naming the procedure
  2. Entering the procedure elements
  3. Ending the procedure definition

Naming the procedure

To define a permanent procedure, enter the PROCEDURE command and a name, as in the following syntax and description. To define a temporary procedure, use PROCEDURE with a negative number or zero instead of a name:

PROCEDURE {procname | n]

where procname is the identifier with which the procedure subsequently can be executed or displayed. The maximum length of procname is 255 characters, and it cannot begin with zero or a minus sign. It is normally an alphanumeric character string and must not contain any of the following special characters:

  • Space
  • Comma
  • End-of-line character
  • Equal sign
  • Single quote
  • Carriage return

If you are defining a temporary procedure, remember that Model 204 automatically assigns numbers (0, -1, -2, ...) to any ad hoc requests you create during the current terminal session, treating them as temporary procedures.

Entering the procedure elements

Model 204 responds to the PROCEDURE command by displaying the prompt:

*** M204.1144: DEFINE PROCEDURE procname

You can now enter commands, statements, or other text to be stored in the procedure.

Model 204 does not check for syntax errors as procedure lines are entered. Errors are found only when the procedure is executed.

Ending the procedure definition

When all lines for the procedure have been entered, issue the END PROCEDURE statement:

END PROCEDURE [procname]

The name of the procedure after END PROCEDURE is optional.

Model 204 responds to the END PROCEDURE statement by displaying the message:

*** M204.1146: PROCEDURE procname DEFINITION ENDED

You also can enter *CANCEL or press the attention key to indicate the end of the procedure definition.

Replacing a procedure definition

If you attempt to define a procedure with the same name as an existing permanent procedure, Model 204 displays the message:

*** M204.1140: PROCEDURE procname ALREADY EXISTS *** M204.1076: DO YOU REALLY WANT TO REPLACE?

You respond with Y or N. Entering Y erases the existing procedure and replaces it with the new one. Entering N takes you out of procedure definition mode.

Procedure aliases and security

The PROCEDURE command also has options with which you can assign an alias to the procedure name or secure the procedure by assigning it to a procedure class.

Creating procedures with the Full Screen Editor

A temporary procedure can be created and defined without the PROCEDURE command by using the Full Screen Editor. The procedure can be stored permanently by giving it a name when you executing the SAVE command. Refer to the Rocket Model 204 Editing Guide for detailed information about building procedures.

Procedure storage

Once a permanent procedure is created, it remains associated with a file until the file is reinitialized or until the procedure itself is redefined or deleted. The procedure is stored in the default file or group procedure file, or in the file specified by an IN clause on the PROCEDURE command. For more information about group procedure files, see Procedure file and update file references.

Each procedure uses at least one page of Table D. When you attempt to store a new procedure or a new version of a procedure in a file where not enough Table D space is available, Model 204 issues a message that indicates there is insufficient space in the file to store the procedure and that the procedure definition is ended.

Once the available Table D space in the file is used, neither a new procedure nor a new version of any of the file's procedures can be stored in the file until more Table D space becomes available. To make more Table D space available, you can delete procedures from the file, or the file manager can use the INCREASE command to add Table D space to the file.

PROCEDURE process example

In the following example, both commands and User Language statements are included. The lines beginning with *** are Model 204 system messages. The other lines are entered by you:

PROCEDURE LOCATE *** M204.1144: DEFINE PROCEDURE LOCATE OPEN VEHICLES BEGIN FORDS: FIND ALL RECORDS FOR WHICH - MAKE = FORD END FIND NO.FORDS: COUNT RECORDS IN FORDS PRINT 'NUMBER OF FORDS = ' WITH - COUNT IN NO.FORDS END CLOSE VEHICLES END PROCEDURE *** M204.1146: PROCEDURE LOCATE DEFINITION ENDED

Operating on procedures

This section describes the Model 204 commands you can use to display, modify, copy, or delete procedures.

Displaying a procedure

As explained in this section, you can use the Model 204 DISPLAY command to display on your terminal the text of a procedure or of multiple or all your procedures, or a list of the file's procedure names. Variations of DISPLAY also provide the following options:

  • Procedure aliases
  • Procedure names
  • Numbers for procedure text lines
  • Procedure classes
  • Access rights for various procedure classes

Procedure aliases, classes and access rights are described later in this page.

Displaying the text of a procedure

The DISPLAY command allows you to display a procedure. The command is entered in this form:

DISPLAY [PROCEDURE] [procname | n}

To display a temporary procedure, do not specify a name. Specify zero or a negative number (-n), where n is no higher than the maximum allowable number of temporary procedures.

Entering the command DISPLAY by itself, without specifying a name, a number, or zero, displays temporary procedure 0.

Model 204 displays the contents of the specified procedure on your terminal, unless the DISPLAY command is preceded by the USE command. In this case the procedure is displayed on the alternate output destination associated with the USE command. see USE command: Directing output for a full explanation of USE facilities.

Displaying multiple procedures

The DISPLAY command can also be used to display multiple procedures simultaneously.

For example, the following command displays four procedures:

DISPLAY PROCEDURE TEST ALPHA -3 0

To display all procedures currently defined for the default file, enter:

DISPLAY PROCEDURE ALL

This version of the command does not display temporary procedures.

To display the names of the permanent procedures defined for the default file, enter:

DISPLAY LIST

Modifying a procedure

The Model 204 Full Screen Editor and Line Editor allow you to modify procedures online. Use the EDIT command to enter the Editor environment and make your changes. For information about using the Editor, see the Rocket Model 204 Editing Guide.

Copying a procedure

You can also use the Full Screen Editor and Line Editor to copy procedures. To copy a procedure, specify a second procedure name in the EDIT command. For example, if you enter the following:

EDIT OLD, NEW

then the edited version of procedure OLD is stored in procedure NEW.

Full Screen Editor and Line Editor operations are described in EDIT command.

You can also use the COPY PROCEDURE command to copy procedures.

Deleting a procedure

To delete a permanent or temporary procedure, enter:

DELETE PROCEDURE procname

or:

DELETE PROCEDURE n

When a procedure is deleted, Model 204 recovers all of the space that the procedure occupied in the file.

Procedure names consisting of special characters

If a procedure's name consists of special characters (for example, ) or _ ), you must enclose the procedure's name in quotes when deleting it. For example, the following command fails:

DELETE PROCEDURE )

However, this next command succeeds:

DELETE PROCEDURE ')'

Deleting procedure aliases with DEASSIGN

The DELETE PROCEDURE command does not delete any aliases assigned to the procedure being deleted. The DEASSIGN command must be issued to delete a procedure alias.

Aliases are described in Using procedure aliases

Unconditional and conditional execution of procedures

You can include (execute) a procedure unconditionally in one of two ways:

  • Submitting a stand-alone procedure by specifying an INCLUDE command at the terminal
  • Including a procedure in a request by specifying an INCLUDE statement in the User Language request

A procedure invoked by an INCLUDE command or statement can contain several requests and system control commands. INCLUDE, used as a command or a statement, is unconditional.

INCLUDE statement

Description

You can unconditionally include another procedure within a User Language request by specifying the INCLUDE statement in the request.

Syntax

The basic form of the INCLUDE statement is:

INCLUDE {procname | n}

Where:

  • procname specifies the name of the permanent procedure to be included.
  • n specifies the number of the temporary procedure to be included. Temporary procedures are always referred to by numbers. The temporary procedure most recently entered is always procedure 0. See Working with temporary procedures.

Processing

During evaluation, the lines of the named procedure are inserted where the INCLUDE statement appears in the request.

Example

Suppose an audit department wants the first page of all its reports to have one standard format. The department would define a procedure as follows:

PROCEDURE TITLEPAGE SET HEADER 2 'MORTON INSURANCE CO.' AT COLUMN 9 SET HEADER 3 'FISCAL YEAR 1990' AT COLUMN 11 SET HEADER 5 'AUDIT DEPARTMENT' AT COLUMN 11 NEW PAGE END PROCEDURE

Thus the request:

BEGIN INCLUDE TITLEPAGE SET.PG.HDR: SET HEADER 2 'POLICYHOLDERS REPORT' AT COLUMN 10 SET HEADER 3 SET HEADER 4 'NAME' AT COLUMN 3 - WITH 'POLICY NO.' AT COLUMN 28 SET HEADER 5 NEW PAGE POL.HOLDERS: IN CLIENTS FIND ALL RECORDS FOR WHICH RECTYPE = POLICYHOLDER END FIND PRINT.REC: FOR EACH RECORD IN POL.HOLDERS PRINT FULLNAME AT COLUMN 3 - WITH POLICY NO TO COLUMN 35 END FOR END

would produce a report in the format shown below.

The first page is headed:

99.218 AUG 06 09.05.00 PAGE 1 MORTON INSURANCE CO. FISCAL YEAR 1990 AUDIT DEPARTMENT

All subsequent pages are formatted:

99.218 AUG 06 09.05.01 PAGE 2 POLICYHOLDERS REPORT NAME POLICY NO. ABBOTT, FRANKLIN G 100340 ABBOTT, HAZEL W 100642 . . . . . .

INCLUDE command

You can unconditionally execute a procedure by using the INCLUDE command. The syntax of the INCLUDE command is the same as that of the INCLUDE statement. If you enter the INCLUDE command without specifying a procedure name or number, Model 204 executes the most recently entered temporary procedure (procedure 0).

Processing

When Model 204 encounters an INCLUDE command, it reads the lines stored in the procedure and executes each system control command in the procedure. Any User Language requests in the procedure are compiled and executed.

The following commands cannot be issued from within a procedure:

  • CREATEG
  • EOD
  • EOJ
  • FILELOAD
  • FLOD
  • LOGWHO
  • REGENERATE
  • RENAME PROCEDURE
  • REORGANIZE
  • RESTART
  • Z

Responses to dummy strings and $READ prompts can be specified as part of the INCLUDE command or statement, as described in Dummy strings in procedures.

Example

If a procedure is included at command level, any User Language statements in the procedure must be preceded by a BEGIN or a MORE command. A procedure can contain several requests and also can contain any number of valid system control commands. For example:

PROCEDURE PRINTS *** M204.1144: DEFINE PROCEDURE PRINTS BEGIN PRINT 'FIRST REQUEST' END RESET LECHO = 4 BEGIN PRINT 'SECOND REQUEST' END RESET LECHO = 0 END PROCEDURE *** M204.1146: PROCEDURE PRINTS DEFINITION ENDED

This procedure, PRINTS, includes END statements for the requests contained within the procedure. The PROCEDURE PRINTS and END PROCEDURE commands are not stored as part of the procedure.

To execute this procedure, enter:

INCLUDE PRINTS

The following display appears:

FIRST REQUEST BEGIN PRINT 'SECOND REQUEST' END SECOND REQUEST RESET LECHO = 0

In this case, the INCLUDE command is not labeled, because it appears as a command rather than in a request.

Conditional inclusion of procedures

The IF command allows a procedure to be included conditionally, depending on the result of a specified test. It is issued in the form:

IF X=Z, procname

where the named procedure is included if the condition is satisfied (in the example, if the global variable X has a value of Z).

Dummy string and $READ responses can be specified as an option on the IF command line. For information about techniques for conditionally including procedures using global variables, see Global features.

Using procedure aliases

A procedure can have more than one name: an actual or official name and any number of alternative names or aliases. For example, the official name might be short and easy to enter and the aliases might be longer and more descriptive. All the names can be used interchangeably. However, access to a procedure by its actual name is slightly faster than access by an alias.

Defining and deleting aliases

You can define an alias with the PROCEDURE command, such as the following:

PROCEDURE COUNT ALIAS=FEMALE.COUNT

An alias also can be assigned after a procedure is defined with the ASSIGN command:

ASSIGN COUNT,FEMALE.COUNT

When a new alias is assigned for a procedure, all existing aliases are preserved.

An alias remains in effect until it is removed by entering a DEASSIGN command. For example:

DEASSIGN FEMALE.COUNT

Deleting the procedure does not automatically delete any aliases that have been established for the procedure. Only the DEASSIGN command removes aliases.

Aliases not legal with RENAME

With nearly all of the Model 204 commands, a procedure alias can be used interchangeably with the official procedure name. When editing, executing, displaying, or deleting a procedure, you can identify the procedure by specifying either its name or its alias. However, if you are changing the official name of a procedure with the RENAME command:

RENAME COUNT, COMPUTE

you must specify the actual name (not an alias) in the command.

Protecting procedure access and manipulation

The procedures in a file are not automatically available to all users. They might be available only for certain users or for certain operations. Procedure access and manipulation are protected by file-level and procedure-level security. This section provides a brief description of the two layers of procedure protection. For a complete discussion of file and procedure security, see Security.

Procedure protection

Procedure protection involves the control of user privileges and procedure accessibility. You must have both of the following to use a given procedure in a file:

  • Privileges that entitle you to operate on (define, modify, delete, and so on) procedures to which you have access. These privileges, or access rights, might permit some procedure operations but not others.
  • The authority to access the procedure.

Access rights

Access rights are a subset of file privileges. When you open a file, you are granted certain file privileges according to the file type and your password, if any. These privileges include the operations on procedures, if any, you are permitted. At this time you are also assigned to a user class, all members of which have the same access rights. Your user class, an arbitrary number in the range 1 through 255, is used in the determination of whether you can access a given procedure.

The access rights for your user class can also later be modified for some or all procedures if the file manager secures file procedures.

See the note on the following page for more information about the effect on privilege determination of modifications to access rights. For more information about file privileges, see File privileges.

Gaining procedure access

The Access Control Table (ACT) included in each file associates users with the procedures they can access. The table holds your file privileges and user class and maps them to the procedure class of the procedures you can access. A procedure class is a number (like user class) assigned to a procedure with the PROCEDURE command or the SECURE command to protect it from unauthorized access.

When you attempt to use a command that operates on a procedure, Model 204 checks the Access Control Table. The ACT simultaneously determines whether you can access the procedure and what access rights you have for the procedure. You are allowed to execute the command or you receive a message that you are not authorized to do so.

Defining procedure classes

Most privileges and other security features at an installation are assigned by the system manager and the file manager. However, users with sufficient user privileges can secure a procedure by assigning the procedure a class when it is defined, using the following format:

PROCEDURE procname PCLASS = n

where n, a number in the range 1 through 255, is the desired procedure class.

When you are defining a new procedure, Model 204 checks your access rights (see the following Note) to determine whether you are allowed to define procedures of the class specified. If you want to redefine an existing nonsecured procedure by adding a class to it, you must have the privilege to change procedures of the specified class. If the procedure being redefined is already secured, you cannot change its class unless you have file manager privileges.

Note: To determine your access rights with regard to a specific operation on a procedure to which you have access, Model 204 first checks whether your file privileges allow you to perform the operation. If they do, Model 204 then checks whether the procedure has been SECUREd. If it has, and if your secured rights do not allow the operation you are attempting, you are informed that you lack authorization to perform the operation.

Controlling procedure security

The file manager can secure existing procedures and also can desecure procedures. The SECURE command secures a procedure by assigning a procedure class to it. SECURE can also limit particular user classes to particular procedure classes. Finally, SECURE can also assign particular procedure operations to particular user classes.

The DESECURE command desecures privileges or removes access rights for particular user or procedure classes.

For more information about Model 204 security features, see Security.

Executing and defining procedures within procedures

Procedures can have a layered construction: they can contain INCLUDEs for other procedures, and they can contain other procedure definitions.

Each of these constructions is discussed in this section.

Nested procedures

Procedures that contain INCLUDE commands and statements are called nested. Procedure nesting can be as many as four levels deep. Thus, procedure A can unconditionally include procedure B; procedure B can unconditionally include procedure C; procedure C can unconditionally include procedure D; and procedure D can unconditionally include procedure E. However, procedure E cannot include additional procedures if procedure A is executed.

You can use the LVLTRC parameter as a debugging tool to trace the level of nesting.

Example

The following example illustrates the order in which Model 204 reads the lines of nested procedures.

The procedures to be used are defined as follows:

Procedure A:

INCLUDE B INCLUDE C

Procedure B:

BEGIN INCLUDE D END

Procedure C:

BEGIN PRINT 'END OF REQUEST' END TIME

Procedure D:

NAMES: FIND ALL RECORDS FOR WHICH - NAME = SMITH PTR: FOR EACH RECORD IN NAMES - . . . processing . . . END BEGIN CTR: FIND AND PRINT COUNT - NAME = JONES

When you enter INCLUDE A, Model 204 reads the lines in the following order:

INCLUDE B BEGIN INCLUDE D NAMES: FIND ALL RECORDS FOR WHICH - NAME = SMITH PTR: FOR EACH RECORD IN NAMES - . . processing . . END BEGIN CTR: FIND AND PRINT COUNT NAME = JONES END INCLUDE C BEGIN PRINT 'END OF REQUEST' END TIME

Defining a procedure within a procedure

You can define procedures from within another procedure. Inner, defined, procedures can be established from the execution of the outer, defining, procedure. The inner procedure is not actually defined until the first procedure is executed.

Example

Entering the statement lines in the following example creates a procedure named MAKE.PROC. When the procedure executes, it prompts you for input and creates the FIND.AND.COUNT procedure with the selection criteria entered from the terminal.

PROCEDURE MAKE.PROC BEGIN IF $SETG('GLOB','??ENTER.FIND.SPEC') THEN PRINT 'GVT FULL' END PROCEDURE FIND.AND.COUNT BEGIN LOOK: FIND ALL RECORDS FOR WHICH -  ?&GLOB CTR: COUNT RECORDS IN LOOK SKIP 1 LINE PRINT COUNT IN CTR AND - 'RECORDS FOUND WITH ?&GLOB' END END PROCEDURE FIND.AND.COUNT END PROCEDURE

Setting dummy string substitution

As the example shows, variable parts of the inner procedure can be specified as dummy strings. (Refer to Dummy strings in procedures.) When the Model 204 SUB parameter is set to 4 (substitution is made in lines from procedures), substitutions are made for dummy strings during execution of the defining procedure. The resulting values are used in the establishment of the defined procedure. To establish a defined procedure that contains dummy strings from within another procedure, option 4 of the SUB parameter must be turned off.

Identifying the procedure ending

Procedure definition is invoked by a PROCEDURE command followed by the procedure name. Subsequent lines are stored as the procedure definition. The end of the procedure definition is indicated by END PROCEDURE. The procedure name can follow END PROCEDURE. For an inner procedure, the procedure name should be appended to the END PROCEDURE.

If the procedure name is entered after END PROCEDURE and the name does not match the name of the outer, defining procedure, the procedure definition is not ended: Model 204 assumes the END PROCEDURE statement is another line of the procedure. Only an END PROCEDURE command without a procedure name or with a procedure name that matches the name of the defining procedure completes the procedure definition.

Working with temporary procedures

Model 204 automatically saves a limited number of a user's most recent requests as temporary procedures. The number of saved requests is controlled by the NORQS parameter, which has a default value of 5.

During the current terminal session, recent ad hoc requests are treated like permanent procedures. They can be executed, displayed, and deleted with the commands described elsewhere in this page. Unlike permanent procedures, however, temporary procedures cannot be named. You can assign them a number or they can be assigned a number automatically by Model 204.

Defining a temporary procedure

If a request is entered from your terminal rather than from a stored procedure, it is known as an ad hoc request. Ad hoc requests are referred to by numbers. Request 0 is either the request that is currently being entered or, if no request is being entered, the most recently entered request. Request -1 refers to the request entered before the most recent one, -2 to the one before that, and so on.

You can also define the number of a temporary procedure explicitly by assigning it a negative number in the PROCEDURE command.

Temporary procedures and ad hoc requests use the same numbering system. NORQS, a UTABLE parameter, determines the total number of temporary procedures and requests.

A temporary procedure can contain commands and other text and need not be only a simple User Language request.

Avoiding the loss of the oldest temporary procedure

When a new request is entered by entering either of the following commands:

BEGIN

or:

MORE

the new request becomes the current one. The previous request, which has been assigned number 0, is now assigned the number -1; -1 becomes -2, and so on. If Model 204 is already maintaining the maximum number of procedures or requests, the oldest is lost.

There are three ways to preserve the oldest request or temporary procedure before replacing it with the next oldest:

  • Use the Editor to insert the phrases PROCEDURE procname and END PROCEDURE before and after the oldest temporary procedure. Then INCLUDE the procedure to define it as a permanent procedure.
  • Redefine the oldest as a permanent procedure with an EDIT command. For example:

    EDIT -4, NEWPROC

  • Use the EDIT command to store the oldest as a more recent temporary procedure. For example:

    EDIT -4, -2

    in which case the old temporary procedure (-2) is deleted.

Running a temporary procedure

Permanent and temporary procedures are retrieved and executed with the INCLUDE command. For temporary procedures, INCLUDE has the form:

INCLUDE n

where n is zero or a negative number.

A temporary procedure is included in the same way that a permanent procedure is: Model 204 executes each system control command in the procedure. In other respects, the way Model 204 responds depends upon the characteristics of the procedure:

  • If the procedure contains one or more User Language requests, Model 204 compiles and executes these requests.
  • If the END statement is omitted from a request in an included procedure, Model 204 compiles the request through the last statement and allows you to continue entering the request. If the temporary procedure has a number other than zero, Model 204 issues an error message.

Dummy strings in procedures

Whenever a procedure is included, it is interpreted line by line from storage exactly as it was input at definition time. However, a special facility of the User Language, dummy strings, allows you to temporarily change certain terms and statements within the procedure each time it is included. When the procedure is defined, items to be replaced at INCLUDE time should be represented by dummy strings.

By responding to a prompt on the terminal, you can enter the replacement values to be inserted in the procedure. As described on Entering dummy string responses in commands, you can also enter these replacement values as part of the command (IF or INCLUDE) or INCLUDE statement with which you initiate the execution of the procedure.

See the following four sections, which describe:

$READ function

In many cases, the use of the dummy string feature can be replaced by the $READ function. For more information, refer to $READ.

Syntax

Dummy strings consist of one of these punctuation mark pairs, followed immediately by the character string to be displayed on the terminal as a prompt:

  • Two question marks (??)
  • Responses to these dummy strings are expected at the I/O level immediately above the level of the dummy string. Thus, if a procedure is nested, a dummy string response to a prompt in the nested procedure would be expected in the procedure that includes the nested procedure.

  • A question mark and a dollar sign (?$)
  • These dummy strings allow you to enter responses from the terminal, regardless of the level of procedure nesting.

  • A question mark and an ampersand (?&)
  • These dummy strings allow Model 204 to obtain responses from the global variable table.

The prompt string can contain any of the characters A-Z, 0-9, or period (.).

When dummy strings are displayed on the terminal, they always appear with two question marks, even if they are ?$ or ?& dummy strings. When the procedure is included, each dummy string is printed on the terminal and the user enters substitute data for it.

Responses to all three types of dummy strings can also be specified in the INCLUDE command, as described on Entering dummy string responses in commands. Model 204 looks for a response in the command before prompting you for a response.

There is no limit to the number of dummy strings that can appear in a procedure.

Producing a report on any field

The following is an example of a procedure which can be used, without modifying the code, to produce a report on any agent:

PROCEDURE AGENT.DATA BEGIN FIND.RECS: FIND ALL RECORDS FOR WHICH AGENT = ??ENTER.AGENT END FIND FOR EACH RECORD IN FIND.RECS PRINT ALL INFORMATION END FOR END END PROCEDURE

When procedure AGENT.DATA is included, the following prompt appears on the terminal:

??ENTER.AGENT

The user then enters the particular agent to be used as the selection criteria for this request (for example, CASOLI). Model 204 replaces the dummy string with the actual value, CASOLI, and compiles the line as if it had read AGENT = CASOLI.

Defining and including a procedure

This example illustrates a procedure definition and the subsequent prompts and replies that occur when the procedure is included.

PROCEDURE CLIENTRPT BEGIN SELECT.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH  ??SELECTION END FIND SORT.RECS: SORT RECORDS IN SELECT.RECS BY ??KEY SET HEADER 1 ??HEADING1 NEW PAGE FOR EACH RECORD IN SORT.RECS PRINT ??REPORT.DATA END FOR END END PROCEDURE INCLUDE CLIENTRPT ??SELECTION STATE = NEW YORK ??KEY POLICY NO ??HEADING1 'NEW YORK DRIVERS' AT COLUMN 10 ??REPORT.DATA POLICY NO WITH FULLNAME AT COLUMN 10

The procedure actually compiles as:

BEGIN SELECT.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH STATE = NEW YORK END FIND SORT.RECS: SORT RECORDS IN SELECT.RECS BY POLICY NO SET HEADER 1 'NEW YORK DRIVERS' AT COLUMN 10 NEW PAGE FOR EACH RECORD IN SORT.RECS PRINT POLICY NO - WITH FULLNAME AT COLUMN 10 END FOR END

The compiler expects one physical line of input for each dummy string.

Using dummy strings to create a group

You want to specify the names of the files that make up a temporary group and the parameter values required for the CREATE command. An example of a procedure that does this using dummy strings follows:

PROCEDURE TAXGROUP CREATE TEMP GROUP TAXES FROM ??ENTER.FILE.NAMES PARAMETER ??ENTER.PARAMETERS.AND.VALUES END PROCEDURE

When the TAXGROUP procedure is included, the first of two prompts is displayed on your terminal:

??ENTER.FILE.NAMES

In response, you enter the particular file names that are to make up the TAX group. For example:

TAX, TABLE2, BENEFITS

Model 204 replaces the dummy string with this list of file names and then displays the second prompt:

??ENTER.PARAMETERS.AND.VALUES

In response, you enter:

PROCFILE=TAX

Model 204 replaces the second dummy string with parameter settings and executes the CREATE command.

Using a dummy string to capture input

If the user wishes to enter more than one line of substitution for a dummy string the original procedure should contain a separate dummy string for each expected line of input:

PROCEDURE EXAMP BEGIN STORE RECORD TEXT = '??TEXT.BEGIN - ??TEXT.CONTINUE - ??TEXT.END' END END PROCEDURE

Although the user is prompted three times, each line acts as a continuation of the one preceding, and all are concatenated with a single space before each continuation to form the value of the field TEXT. If all desired data has been entered before the prompts end, the user can respond to additional prompts with a carriage return.

Entering dummy string responses in commands

The value of a ?? or ?$ dummy string can alternatively be entered as part of the INCLUDE or IF command or in an INCLUDE statement. Model 204 accepts the values passed by the INCLUDE or IF as replacements for the dummy strings in the procedure. The dummy string responses are not prompted for if they are entered in advance on the INCLUDE line.

Referring to the example, Producing a report on any field, you could execute the AGENT.DATA procedure by entering:

INCLUDE AGENT.DATA CASOLI

instead of waiting for Model 204 to prompt for the agent by displaying:

??ENTER.AGENT

Delimiter characters for multiple responses

Any number of responses can be specified on the INCLUDE line. Responses must be separated by one of the following delimiters. The character immediately following the name is used as the delimiter.

  • Blank
  • Comma
  • Equal sign
  • Left parenthesis
  • Right parenthesis

The list of responses can be continued using either a trailing hyphen or the continuation column.

To execute the TAXGROUP procedure (from the example Using dummy strings to create a group) with a single command, you can enter:

INCLUDE TAXGROUP TAX,TABLE2,BENEFITS PROCFILE=TAX

instead of waiting for the Model 204 prompts for the file names and parameters:

??ENTER.FILE.NAMES ??ENTER.PARAMETERS.AND.VALUES

The space between TAXGROUP and TAX is the delimiter; the commas and equal sign are actually part of the string (the value of the variable). Model 204 replaces the dummy strings in the procedure with the following values:

TAX,TABLE2,BENEFITS PROCFILE=TAX

Mixing dummy string and $READ responses in the INCLUDE or IF line

Responses to both dummy strings and the $READ function can be specified in the INCLUDE or IF line. Dummy string responses must appear first, followed by $READ responses.

If any $READ responses are included in the list, the list also must include a response for each dummy string that is encountered before the first $READ is executed.

As dummy strings and $READs are encountered in the procedure that is being included, entries are retrieved from the list specified in the INCLUDE or IF line. If there are more dummy strings and $READs than responses in the list, Model 204 retrieves entries from the list and then prompts for the remaining dummy strings and $READs.

Example

This procedure contains one dummy string and one $READ function.

PROCEDURE DUMMY BEGIN GET.A: %A = $READ('SECOND PROMPT') PRINT %A AND '??FIRST.PROMPT' END END PROCEDURE

The user can run this procedure by entering:

INCLUDE DUMMY,ONE,TWO

The resulting output would be:

TWO ONE

Using *CANCEL to return to command level

If the user responds to a dummy string prompt with *CANCEL, Model 204 terminates compilation, ends all procedures, and returns control to the command level at the user's terminal.

Specifying dummy strings in nested procedures

Dummy string substitution lines are entered from the level at which the procedure was included.

If INCLUDE is entered at the terminal by the user, the input line substitution is requested from the terminal or is taken from responses entered as part of the terminal INCLUDE line.

Suppose, however, the user includes procedure TEST, and procedure TEST in turn includes procedure REPT. If procedure REPT contains dummy strings, Model 204 expects the substitution lines to be provided from within procedure TEST.

Substitution lines, one per dummy string, should follow immediately after the INCLUDE REPT statement in the definition of procedure TEST.

Example

PROCEDURE TEST BEGIN POL.NO: FIND ALL RECORDS FOR WHICH POLICY NO = ??ENTER.POLICY.NO END FIND INCLUDE REPT FULLNAME AND DRIVER ID POLICY NO AND STATE END END PROCEDURE PROCEDURE REPT FOR EACH RECORD IN POL.NO PRINT ??REPORT.1 END FOR FOR EACH RECORD IN POL.NO PRINT ??REPORT.2 END FOR END PROCEDURE

Assume that the user includes the procedure TEST from his/her terminal. The user is prompted with ??ENTER.POLICY.NO and enters a valid policy number. When procedure REPT is included from procedure TEST, the user is not prompted. Model 204 automatically substitutes FULLNAME AND DRIVER ID for ??REPORT.1 and POLICY NO AND STATE for ??REPORT.2.

User parameters

The SUB, PROMPT, and LSECHO user parameters control prompting and line substitution for dummy strings.

Specifying dummy string responses in the INCLUDE command

To specify dummy string responses in the INCLUDE command instead, the user can issue:

INCLUDE TEST, 100340

Therefore, the INCL.REPT statement in procedure TEST could be written:

INCL.RPT:INCLUDE REPT,FULLNAME AND DRIVER ID,POLICY NO AND STATE

Using ?$ and ?& dummy strings

Using ?$ dummy strings

Description

The user controls the level at which substitutions are entered by prefixing the dummy strings with ?$ instead of ??. The ?$ causes Model 204 to expect line substitutions for those dummy strings from the user's terminal, no matter how deeply the procedure containing the dummy string is nested.

Example

For example, suppose the previously defined procedure REPT contained:

FOR EACH RECORD IN POL.NO PRINT ?$REPORT.1 END FOR

Then ??REPORT.1 would appear at the terminal and the user would enter a substitution line there, and not from within procedure TEST. The dummy string response alternatively can be specified in the INCLUDE command that invokes TEST.

Using ?& dummy strings

Description

A user can read dummy string responses from the global variable table, GTBL, by prefixing them with ?&. Global variables are discussed in Global features.

This facility allows systems or requests to communicate with each other. In the dummy string specification:

?&globalname

globalname identifies the variable to be read from the global variable table. The value of the named variable is substituted for the dummy string. If the variable is not defined in the table, the variable name specified in the dummy string is displayed on the user's terminal as a prompt. The user then enters the replacement value, as shown below. The response to a ?& prompt cannot be specified as an argument in an INCLUDE line as other dummy string responses can be.

Note: Do not use global variable names containing an underscore (_) in ?& dummy strings. The underscore is not a valid character for dummy strings. An underscore in a ?& dummy string causes the string to be truncated. For example, the ?& dummy string:

?&TEST_GLOBAL

is interpreted as looking for a global variable named TEST.

Example

Suppose the REPT procedure contains:

FOR EACH RECORD IN POL.NO PRINT ?&REPORT.1 END FOR

If the global variable table does not contain a value for REPORT.1, Model 204 displays:

??REPORT.1

The user then responds with the desired value, for example:

FULLNAME AND DRIVER ID

Repeating dummy strings

It often is necessary to repeat a dummy string several times within a procedure, even though only a single response is desired.

Example

PROCEDURE SORT BEGIN . . SORT.RECS: SORT RECORDS IN FIND.RECS BY ??FIELDS FOR EACH RECORD IN SORT.RECS PRINT ??FIELDS END FOR END END PROCEDURE

When including this procedure the user is asked to supply the same fields twice. For example:

INCLUDE SORT ??FIELDS AGENT AND FULLNAME ??FIELDS AGENT AND FULLNAME

Technique 1

You can overcome the inconvenience of the user having to enter the same fields twice by using the following technique. First, the ?& form of the dummy string prompt can be used by adding a brief request at the beginning of the procedure (continued on next page):

PROCEDURE SORT BEGIN %F IS STRING LEN 255 %F = '??ENTER.FIELDS' TABLE.FULL: IF $SETG('FIELDS',%F) THEN PRINT 'GLOBAL VARIABLE TABLE FULL' END IF END BEGIN . . SORT.RECS: SORT RECORDS IN FIND.RECS BY ?&FIELDS PRINT.FL: FOR EACH RECORD IN SORT.RECS PRINT ?&FIELDS END FOR END END PROCEDURE

The new request prompts the user for the sort criteria and includes it in a global variable, FIELDS. This is the only prompt the user sees. The global variable table now contains the variable FIELDS and its value as entered by the user. When evaluation of the second request reaches the ?&FIELDS dummy string in the SORT.RECS and PRINT.FL statements, the response is taken from the value in the global variable table. No prompt appears at the user's terminal.

The global variable is set in a separate request, because dummy strings prompt the user at compile time. If it were in the same request, the user would be prompted, %F would be set, and the TABLE.FULL statements would be compiled but not performed until evaluation. The compiler would then reach the SORT.RECS statement. There would be no value for FIELDS in the global variable table, thus the user would receive a second prompt. The value still would not be saved, and the user would be prompted a third time in the PRINT.FL statement.

Technique 2

Another alternative is to edit the SORT procedure. (Model 204 editors are discussed in the Rocket Model 204 Editing Guide.)

For example:

PROCEDURE SORT EDIT SORTX, 0 99 (R/FIELDS/??FIELDS/:) GO END PROCEDURE PROCEDURE SORTX . . . SORT.RECS: SORT RECORDS IN FIND.RECS BY FIELDS FOR EACH RECORD IN SORT.RECS PRINT FIELDS END FOR END END PROCEDURE

When procedure SORT is included, the user is asked to supply the field names only once (during the edit). The Editor inserts the field names into a copy of procedure SORTX in the appropriate places (replacing each occurrence of FIELDS). Finally, the edited copy of SORTX is saved as temporary procedure 0 and is executed.

This technique can, of course, be extended to handle several dummy strings at once. Another benefit is that once the dummy strings have been supplied, the user can rerun the same request without being asked for dummy strings. The user does this by keying INCLUDE 0.

Using Model 204 parameters to control dummy strings

Three parameters control the use of dummy strings:

  • SUB determines whether, and at what I/O levels, dummy string substitution takes place.
  • PROMPT regulates the system prompting action when dummy strings and $READ and $ENTER functions are encountered.
  • LSECHO governs the echoing of lines in which dummy string substitution takes place.

Input/Output levels direct dummy string replacement

An explanation of input/output (I/O) levels helps to distinguish between types of dummy strings and to understand the details of setting SUB and PROMPT. Input/output for the normal device, your terminal, usually has an I/O level of zero. Each time an INCLUDE is encountered, the I/O level is increased by one, up to a maximum of five. At the end of the included procedure, the I/O level is decreased by 1.

When a ?? dummy string is found in the input stream, at any I/O level, Model 204 gets the replacement for it from the current I/O level minus one. The replacement for a ?$ dummy string always comes from I/O level 0 (the terminal). ?& responses also come from level zero, if the prompt string cannot be found in the global variable table.

Using PROMPT to control dummy string substitution

The default setting (9) for the PROMPT parameter implies that dummy string, $READ, and $ENTER prompting occurs at the terminal. Even if you set PROMPT= to a value to suppress the display of dummy string substitution at a particular I/O level, the system still makes the substitution if the SUB parameter is properly set and a dummy string is present.

Example and discussion featuring PROMPT

Two procedures are defined:

PROCEDURE INNER RESET PROMPT = 5 BEGIN PRINT '??DUMMY1' END END PROCEDURE PROCEDURE OUTER INCLUDE INNER ??DUMMY2 END PROCEDURE

If you execute the procedure INNER, the following sequence occurs:

INCLUDE INNER ??DUMMY1 Prompt for substitution. YELLOW Substitute. YELLOW Result of PRINT statement.

If you execute the procedure OUTER, this sequence occurs:

INCLUDE OUTER ??DUMMY1 ??DUMMY2 YELLOW

In this case, the prompt ??DUMMY2 becomes itself the response that is taken for the prompt ??DUMMY1; but because it is also a dummy string, the substitution is not actually made until you enter YELLOW. This result occurs for the following reasons:

  • The line INCLUDE OUTER is entered at I/O level 0.
  • Procedure OUTER at I/O level 1 includes procedure INNER at I/O level 2.
  • Model 204 expects to get the substitute for ??DUMMY1 from I/O level 1, procedure OUTER. (When a ?? dummy string is found in the input stream, at any I/O level, Model 204 gets the replacement for it from the current I/O level minus 1.)
  • ??DUMMY2 comes from level 0; the replacement for ??DUMMY2, YELLOW, becomes the value in procedure OUTER that is replaced for ??DUMMY1 and printed by procedure INNER.
  • The prompt ??DUMMY1 is displayed because the PROMPT setting is 5 (the sum of options 4 and 1), which directs the display of the prompt if its replacement is expected from a procedure. Had PROMPT been set to 1, only ??DUMMY2 would have been displayed.

Using SUB to control dummy string substitution

The SUB parameter default setting is 4, which makes dummy string substitutions in lines from procedures (I/O levels greater than 0), but not from the terminal. If you can enter a dummy string as part of a procedure definition, no substitution is requested until you include the procedure.

When SUB = 1 (substitution in lines from the terminal) or SUB = 5, the system takes special action when a request is entered. If a dummy string is entered as part of the request, Model 204 drops from I/O level 0 to I/O level -1, and immediately requests the substitute for the dummy string. After the END statement is entered, the request is run using the substituted string. However, the stored temporary procedure retains the original dummy string.

Example

Suppose you enter and run this short request:

RESET SUB=5, PROMPT=5, LSECHO=5 SUB X'05' SUBSTITUTION CONTROL PROMPT X'05' PROMPT CONTROL LSECHO X'05' LINE SUBSTITUTION ECHO BEGIN LOOK: FIND ALL RECORDS FOR WHICH ICE CREAM = ??FLAVOR ??FLAVOR CHOCOLATE ICE CREAM = CHOCOLATE CTR: COUNT RECORDS IN LOOK PTR: PRINT COUNT IN CTR END 24

You reply CHOCOLATE to the prompt ??FLAVOR. Model 204 then echoes (because LSECHO=5) ICE CREAM = CHOCOLATE, indicating that the substitution took place.

Because SUB=5, ??FLAVOR and not CHOCOLATE is retained when the request is saved as temporary procedure 0. You can easily execute the request again (since it is saved as temporary procedure 0) and substitute a different flavor:

INCLUDE 0 ??FLAVOR VANILLA ICE CREAM = VANILLA 32