$BldProc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 62: Line 62:
</p>
</p>
<b>Example</b>
<b>Example</b>
<p>This sample request saves the size of the global variable table (GTBL) before the table is reset with the UTABLE command. (See [[Large request considerations#User Language internal work areas|User Language internal work areas]] for information on the UTABLE command and GTBL.) By saving the LGTBL value, the table can be returned to its original size at a later time. This is particularly useful in a subsystem where the LGTBL parameter is normally reset. (To learn about subsystems, see [[Application Subsystem Development#Application Subsystem Development|Application Subsystem Development]].)    </p>
<p>This sample request saves the size of the global variable table (GTBL) before the table is reset with the UTABLE command. (See [[Large request considerations#User Language internal work areas|User Language internal work areas]] for information on the UTABLE command and GTBL.) By saving the LGTBL value, the table can be returned to its original size at a later time. This is particularly useful in a subsystem where the LGTBL parameter is normally reset. (To learn about subsystems, see [[Application Subsystem development]].)    </p>
<p class="code">BEGIN
<p class="code">BEGIN
%X = $BLDPROC(-1,'BEGIN','OPEN')
%X = $BLDPROC(-1,'BEGIN','OPEN')

Revision as of 20:18, 21 January 2014

The $BLDPROC function enables a request or series of requests to build a temporary procedure. $BLDPROC is similar to the PROCEDURE system control command.

The procedure built by $BLDPROC can contain arbitrary commands or User Language statements or other text. You can execute this procedure after the building request has ended, or you can edit the temporary procedure into a permanent procedure. The number of lines output to a temporary procedure by the $BLDPROC function within a request are controlled by the MOUT parameter. For more information on temporary procedures, see Working with temporary procedures.

You can build only one procedure at a time. To add text to more than one procedure in rotation, you must close one procedure and reopen the next procedure.

Syntax

The format of the $BLDPROC function is:

$BLDPROC (proc number,text,action)

where:

  • proc number is a temporary procedure number. The number of procedures or requests saved for a user is controlled by the NORQS parameter, which has a default value of 5. Procedure number 0 is the request currently being entered. Procedure -1 refers to the request entered before the most recent one, -2 to the one before that, and so on. Therefore, proc number must have a value between 0 and -NORQS+1.
  • text is usually a single line to be appended to the temporary procedure. A single call to $BLDPROC can add more than one line of text by imbedding LINEND parameter characters (usually semicolons) in the text argument. If the text argument is null, the procedure is not changed.
  • action must be one of the options listed in the following table. Building a temporary procedure is similar to building a sequential file in that the procedure must be opened before any text can be added to it. When all of the desired text has been added, the procedure should be closed.
  • Choose from these options:

Option Result
APPEND Adds the text to the end of an already opened procedure.
CLOSE Closes the temporary procedure, disallowing further APPENDs. Model 204 automatically closes any procedure left open at the end of execution of the request. Text specified in a CLOSE call is added before the close.
OPEN Creates a new temporary procedure. If the procedure already exists, the old text is automatically deleted. Text specified in the same $BLDPROC call as OPEN is added after the procedure is opened.
REOPEN Prepares an existing procedure for the addition of text. REOPEN locates the end of the old text so that new text is appended. OPEN and REOPEN are identical for a new procedure. Text specified in the same $BLDPROC call as REOPEN is added after the procedure is opened.

A null or omitted action argument is the same as APPEND.

How $BLDPROC works

$BLDPROC returns a 0 for success and a 1 for any of the following errors:

  • The proc number argument is not numeric or is not in the range of valid temporary procedure numbers.
  • The specified temporary procedure is being included.
  • Where a previous USE PROC command is also directing output to the same temporary procedure.
  • The action argument is not one of the valid choices.
  • The action argument is OPEN or REOPEN and there is already an open temporary procedure.
  • The action argument is APPEND or CLOSE and there is no open procedure.
  • The action argument is APPEND or CLOSE and the proc number argument does not match the currently opened procedure.

Temporary procedures are stored in CCATEMP. If an additional CCAPTEMP page is required to process a $BLDPROC call, but CCATEMP is full, then the request is cancelled and the entire temporary procedure is deleted. After the request is cancelled, the procedure does not contain everything up to the point of failure. In the event of CCATEMP filling while processing $BLDPROC, the following message is issued:

*** CANCELLING REQUEST: M204.0441: CCATEMP FULL: $BLDPROC

Example

This sample request saves the size of the global variable table (GTBL) before the table is reset with the UTABLE command. (See User Language internal work areas for information on the UTABLE command and GTBL.) By saving the LGTBL value, the table can be returned to its original size at a later time. This is particularly useful in a subsystem where the LGTBL parameter is normally reset. (To learn about subsystems, see Application Subsystem development.)

BEGIN %X = $BLDPROC(-1,'BEGIN','OPEN') %X = $BLDPROC(-1,'%A = $SETG(GTBL,' WITH - $VIEW('LGTBL') WITH ')') IF %A THEN PRINT 'GLOBAL TABLE FULL' END IF %X = $BLDPROC(-1,'END','CLOSE') IF %X THEN PRINT 'BLDPROC ERROR' END IF END UTABLE LGTBL 15000

After the preceding request executes, procedure -1 contains the following statements:

BEGIN %A = $SETG('GTBL',704) END