Subroutines.

A subroutine is a series of instructions that a program invokes to perform a specific task. There are many reason to gather together a block of instructions in a subroutines: usually, a set of instructions that can be recalled from many point of the program and that are enough insulated to be like a subprogram. In Hilmas another reason is to overcome adressing limitations that can happen in a big program. Anyway, is good programming practice subdivide a problem in many small tasks, as far as possible insulated.

Subroutines in Hilmas may be internal, in the same source file and following the main, or external and therefore in another source file, compiled separately and written in a language that can be different by Hilmas.

 

Internal subroutines.

The instruction that invokes the internal subroutine is the GOSUB instruction, specifying the subroutine name. The GOSUB instruction may be used several times in a program to invoke the same subroutine and can be used also inside a subroutine to recall another subroutine. A subroutine can even recall itself, that is can be recursive, but with some added parameters (see later).
Internal subroutine body is started by SUBDEF instruction with the name of the subroutine; when the subroutine ends, it returns control to the instruction that directly follows the GOSUB. The instruction that terminate the coding of subroutine is the ENDSUB, whereas if you want leave the subroutine before its natural end you must use SUBEXIT statement.

Internal subroutines must be written in the same source of the calling program and its position is before ENDPROG statement; so main program must end with a EXIT statement, immediately before the first SUBDEF definition. So a new outline of a Hilmas program can be:

  COPY HILMAS
PROGRAM program-name,operating-system
    body of program, with call to subroutines
EXIT
SUBDEF sub-name-1
    body of subroutine 1
ENDSUB
[local variables of subroutine 1]
SUBDEF sub-name-2
    body of subroutine 2
ENDSUB
[local variables of subroutine 2]
[more subroutines .....]
ENDPROG
  COPY HILVAR
global variables definition
  END

All global variables are visible from an internal subroutine, (there is not variable-scope in Hilmas) and so there isn't a passing parameter problem in this type of subroutine. An Hilmas internal subroutine is similar to a Cobol routine recalled by PERFORM, or a old Basic subroutine recalled with a GOSUB. A drawback of this lack of variable-scoping is that every variable, if is written in the same source, must have a unique name, no matter that is used only in a subroutine. So be care that variables used by subroutines can modify variables used by main program if have the same name.

Variables used by a subroutine can be defined (and only if you want) immediately after its ENDSUB statement (we have named local variables), these anyway are always global variables and can be defined here only for self documentation purposes. These can (not necessarily) be seen (and used) from the main or from the preceding subroutines. Using these pseudo-local variables can be useful especially if there are addressing problems because there are too much global variables. Note that these pseudo-local variables cannot be used in CICS environment, because all CICS programs can be used by many users and must be reentrant.

External subroutines.

The instruction that invokes the external subroutine is the CALL instruction. Invoked routine can be written in every compiled language that obeys standard IBM calling convention, including Hilmas itself.

CALL subroutine[,(param1,param2,...)]

Besides subroutine name, can be specified al list of variables to be passed to called program.

If you write an external subroutine in Hilmas, it hasn't PROGRAM and ENDPROG instructions, it starts with ROUTINE instruction and ends with RETURN. The only variables of the calling program that are visible to a routine are the variables passed at calling time: these must be defined in ROUTINE instruction and must correspond in type, order and length to variables in calling program. For any other thing, an external routine is equal to a main program that can have itself any number of internal or external routine.
An external routine written in Hilmas can be called by program written in any language, provided that standard IBM calling convention is used.

A generic outline of a Hilmas external routine can be:

  COPY HILMAS
ROUTINE routine-name,operating-system[,(param1,param2,...)]
    body of routine
EXIT
SUBDEF sub-name-1
    body of internal subroutine 1
ENDSUB
[local variables of subroutine 1]
[more internal subroutines .....]
RETURN [(param1,param2,...)]
  COPY HILVAR
variables definition
  END

Whereas IBM calling convention is a parameter passing by address, it is transformed by Hilmas into a value passing, so original values in calling program are never modified and routine works only on a local copy of the passed parameters. Original values of the parameters can be modified adding a list of parameters to RETURN statement, that ends the subroutine. This list is optional; if used, usually is the same list of parameter passed to ROUTINE statement; optionally can be shorted if you don't want give back the last parameters; every variable can also be replaced by a point (.) if you want to skip return of this variable.

External routines are always written and compiled in a separate source as regards main program, so every variable is unknown and independent by the calling program; remember that also files opened by calling program are inaccessible by routines; every routine can open, close and manage own files (inaccessible from main), whereas screen I/O can be safely used by an external subroutine.