Procedures

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:

• Entering dummy string responses in commands
• Specifying dummy strings in nested procedures
• Using ?$ and ?& dummy strings
• Repeating dummy strings

$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