$BldProc

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 SOUL 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 about 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 (procNumber, text, action)

Where:

• procNumber 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, procNumber 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 procNumber 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 procNumber argument does not match the currently opened procedure.

Temporary procedures are stored in Using_the_system_scratch_file_(CCATEMP)\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 creates UTABLE commands to restore three server table sizes (LVTBL, LGTBL, and LSTBL) before the table sizes are reset; INCLUDE -1 at a later point will restore the table sizes. (See User Language internal work areas for information on the UTABLE command.) This can be useful in a subsystem where the server table sizes are normally reset.

begin %x is float %x = $bldProc(-1, 'UTABLE LVTBL ' $view('LVTBL'), 'OPEN') %x = $bldProc(-1, 'UTABLE LGTBL ' $view('LGTBL')) %x = $bldProc(-1, 'UTABLE LSTBL ' $view('LSTBL'), 'CLOSE') if %x then print '$BldProc error ' %x end if end UTABLE LGTBL 15000

After the preceding input stream executes, procedure -1 contains the following (assuming these were the server table sizes):

UTABLE LVTBL 1300 UTABLE LGTBL 2000 UTABLE LSTBL 10000

Note: You can also use the PUSHUTABLE and POPUTABLE commands to preserve and restore these table sizes.

The following procedure code is an example of the usefulness of $BldProc for running dynamic code on the same thread from within a subsystem:

begin $setg('NEXTPROC','SOMEWHERE_ELSE') %x = $bldProc(-1,'begin','OPEN') if %(system):currentTimeMilliseconds:mod(2) then %x = $bldProc(-1,'in SOMEFILE include SOMETHING_ODD') else %x = $bldProc(-1,'in SOMEFILE include SOMETHING_EVEN') end if %x = $bldProc(-1,'end','CLOSE') end I -1 DELETE -1

As soon as control returns from whichever of the above INCLUDE statements that is run, the subsystem navigates to the next specified procedure (within the global NEXTPROC; in this case SOMEWHERE_ELSE).