Kilowatt Software's Classic Rexx Tutorial Language Level 4.00 (TRL-2)

Procedure instruction

procedureNameLabel : [ procedure [ expose variableList ] ]

where:
variableList is one or more symbol names separated by spaces. When a symbol name is enclosed in parentheses it is a special reference variable as described in the variable reference section below.

The procedure instruction begins an internal procedure. The instruction is preceded by a label, which is the name of the internal procedure. Multiple labels can precede the procedure. It is not necessary to specify a procedure instruction, as will be described below.

Warning: if execution inadvertently flows into a procedure instruction, this will cause error code 17 (unexpected procedure) to be raised. This problem is generally corrected by preceding the procedure instruction's label(s) by an return or exit instruction. This problem can also occur when a signal instruction transfers to an incorrect label.

When execution inadvertently flows into a procedure that lacks a procedure instruction an unexpected procedure WILL NOT be raised. This can lead to a variety of unexpected consequences. When this type of procedure is initially created you are strongly advised to precede the associated label(s) with an return or exit instruction.

The procedure instruction is not used in the initial program of an external procedure. Consequently, variables of the calling program are never exposed within external procedures.

Click here to review the structure of Rexx programs and procedures.

Exposure of calling program variables

You can use three different methods of exposing calling program variables in internal procedures. This is controlled by using the optional procedure instruction, which can be followed by an optional list of specific variables to expose.

Method 1 -- no variables exposed

If the procedure instruction is specified, without an exposed variable list, then none of the calling program's variables are exposed. Since variables aren't exposed, the internal procedure can only obtain arguments from the calling procedure, and return a result.

Hint: you will generally want to expose none of the calling program's variables, because this is the least problematic method.

  /* main program */
  do n=1 to 5
    say 'The factorial of' n 'is:' factorial( n )
    end
  return

  factorial : procedure  /* none of the caller's variables are exposed */
    n = arg(1)  /* n is a local variable */
    if n = 1 then
      return 1
    x = n
    n = n - 1  /* ok, this is a local variable */
    return x * factorial( n )

Method 2 -- ALL variables exposed

When the procedure instruction is omitted, all of the calling program's variables are exposed.

Hint: you should generally AVOID the exposure of all variables, because it is VERY problematic. When this type of procedure is initially created you are strongly advised to precede the associated label(s) with an return or exit instruction.

  abc :   /* all of the caller's variables are exposed -- YIKES !! */
    parse arg a, b, c
    ...procedure logic appears here
    ...reference caller variables as necessary
    ...modify caller variables as a last resort
    return 1  /* return a result to the caller */

When the internal procedure is merely referencing the values of the calling program's variables, then no problems should ensue. However, if the internal procedure m-o-d-i-f-i-e-s a variable, it might be revising a calling program's variable, even if it looks like the variable is local to the procedure.

The following shows how the absence of a procedure instruction can lead to an infinite loop.

  /* main program */
  do n=1 to 5
    say 'The factorial of' n 'is:' factorial( n )
    end
  return

  factorial :   /* all of the caller's variables are exposed -- YIKES !! */
    if n = 1 then
      return 1
    x = n
    n = n - 1  /* this is the caller's variable n -- ugh. */
    return x * factorial( n )

Method 3 -- specific variables exposed

Fortunately there is another option -- to expose a specific set of the calling program's variables. This is done by using the expose clause after the procedure keyword. The specific variables that are exposed are identified after the expose keyword. The same variable(s) can be exposed through multiple procedure levels.

There are three types of variables that can be exposed.

1. simple variable -- N, X, first_name
This exposes a simple variable.: 2. compound variable -- color.favorite, array.N
This exposes a compound variable.
Beware: the order of variable exposure can be significant. Assume N is 7 in the calling program. If array.N is exposed, and N was previously exposed in the expose clause, then the variable that is exposed is ARRAY.7 . However, if N was not previously exposed in the expose clause then the variable that is exposed is ARRAY.N .: 3. compound stem variable -- color., array.
When a compound stem variable is exposed, that variable and all compound variables that begin with the stem are exposed.

Hint: you should expose specific variables cautiously, because it is somewhat problematic.

The following shows how the the misuse of an exposed variable can lead to an infinite loop.

  /* main program */
  do n=1 to 5
    say 'The factorial of' n 'is:' factorial( n )
    end
  return

  factorial : procedure expose n /* only exposing n seems to be ok */
    if n = 1 then
      return 1
    x = n
    n = n - 1  /* oops, this is the caller's variable n -- ugh. */
    return x * factorial( n )

Variable reference

Within the list of variables that follows the expose keyword, one additional capability can be used. A variable name can be enclosed in parentheses. This exposes the specific variable, and addition its value is used as a subsidiary list. The list consists of a series of variable names separated by spaces. These are exposed in sequence left to right. The names that are exposed follow the same rules as the original exposure list -- i.e. how simple, compound, and stem variables are exposed.

Note: the variable reference capability was added in language level 4.0 (TRL-2). Thus, this capability may be absent in some Rexx implementations.

Here is a simple example of the use of a variable reference in a procedure instruction's expose clause.

/* main procedure */

varlist = 'a b c'
call getvalues
say a b c
return 0

getvalues : procedure expose (varlist)
  parse value 'abra ca dabra' with a b c
  return

A detailed example of exposed variables

Here is a detailed example of a program that uses exposed variables in various procedures

  /* TopoSort.rex
   topological sort

   identifies the order of dependences from most dependent to least dependent

   usage
    rexx TopoSort [MixedCase] < infile > outfile

   example input file -- a series of dependency definitions:

      +-------+
      |  a b  |
      |  b c  |
      |  b e  |
      |  c d  |
      |  b f  |
      |  m n  |
      |  n o  |
      |  o p  |
      |  m r  |
      |  m s  |
      +-------+

   corresponding output file a tree showing levels of dependency:

      +-------------+
      |A            |
      |+ B [A]      |
      |++ C [B]     |
      |+++ D [C]    |
      |++ E [B]     |
      |++ F [B]     |
      |M            |
      |+ N [M]      |
      |++ O [N]     |
      |+++ P [O]    |
      |+ R [M]      |
      |+ S [M]      |
      +-------------+
  */

  if translate( left( arg(1), 1 ) ) = 'M' then
    characterCase = 'M'

  else if arg(1) <> '' then do
    call lineout !, 'Usage'
    call lineout !, ' rexx TopoSort [MixedCase] <infile >outfile'
    exit 1
    end

  else
    characterCase = 'U' /* default is Parentcase */


   /* use parse to do multiple variable assignment
    * nItems = 0
    * nLevels = 0
    * itemDepth. = 0
    * items = ''
    * dependsOn. = ''
    * dependeeOf. = ''
    * shownItems = ''
    * prevFrom = ''
    */

  parse value 0 0 0 with ,
    nItems nLevels itemDepth. ,
    items dependsOn. dependeeOf. shownItems prevFrom

  do lines()

    if characterCase = 'U' then
      parse UPPER linein From To .
    else
      parse linein From To .

    if From = To | DetectCycle( To ) then do
      call lineout !, 'Cycle detected.' From '<->' To'...'
        exit 1
        end

    dependsOn.From = dependsOn.From To

    dependeeOf.To = dependeeOf.To From

    call ReviseDepth From To

    call AddItem From

    call AddItem To

    if From <> prevFrom then do
      /* call lineout !, From */
      prevFrom = From
      end

    end /* end lines() loop */

  do i=nLevels to 0 by -1

    replicas = items

    do while replicas <> ''
      parse var replicas From replicas
      if itemDepth.From = i then
        call ShowItem From '_'
      end

    end

  exit 0
    
  ReviseDepth : procedure expose nLevels itemDepth. dependeeOf.

    parse arg From To

    itemDepth.From = max( itemDepth.From, itemDepth.To + 1 )

    nLevels = max( nLevels, itemDepth.From )

    /* debugging...
    if length( dependeeOf.From ) > 1 then
      say copies( '.', 1 + itemDepth.From ) From '->' dependeeOf.From
    */

    dependees = dependeeOf.From

    do while dependees <> ''
      parse var dependees dependee dependees
      call ReviseDepth dependee From
      end

    return
    
  AddItem : procedure expose nItems items

    parse arg Item

    if wordpos( Item, items ) = 0 then do
      items = items Item
      nItems = nItems + 1
      end

    return
    
  ShowItem : procedure expose nLevels shownItems itemDepth. dependsOn.

    parse arg Item Parent

    itemSeenBefore = ( wordpos( Item, shownItems ) > 0 )

    if itemSeenBefore & parent = '_' then
      return

    if Parent = '_' then
      say Item
    else
      say copies( '+', 1 + (nLevels - itemDepth.Parent) ) Item '['Parent']'

    if \ itemSeenBefore then
      shownItems = shownItems || copies( ' ', shownItems <> '' ) || Item

    dependees = dependsOn.Item

    do while dependees <> ''
      parse var dependees To dependees
      call ShowItem To Item
      end

    return
    
  DetectCycle : procedure expose From dependsOn.

    parse arg To

    if wordpos( From, dependsOn.To ) > 0 then
      return 1

    return 0

Kilowatt Software's -- Classic Rexx Tutorial -- Back to top Click here if you have any comments or questions regarding this tutorial

Last updated on: 8 Aug 2002