- Calling an External Subroutine from Logic

PROIV uses the LINK or LINK-CRT statement to invoke a procedural language routine. Both statements transfer control from a PROIV logic module to a procedural language routine. LINK-CRT is provided for support for external subroutines that perform input or output at the user's terminal since it provides for screen clearing and refreshing. When the subroutine has finished executing, processing control automatically returns to the PROIV logic statement immediately following the LINK statement.

Syntax

LINK (sub-name) or LINK-CRT (sub-name)
or
LINK (sub-name{,arg}...) or LINK-CRT(sub-name{,arg}...)

Syntax Elements

sub-name is the name defined in the subroutine name table in extsub.c which is then used to determine which subroutine to call.

arg is optional. Arguments are passed to and from the called subroutine by reference. All arguments (representing PROIV strings and PROIV numerics) are passed as null terminated strings to the called subroutine. Strings are padded with trailing spaces to the maximum length of the variable being passed. Numerics are padded with leading zeros to the maximum variable width. Arguments returned to PROIV should be similarly structured.

Remarks

LINK-CRT performs the following actions:

Flushes any pending PROIV screen output.
Resets terminal connection characteristics to those in effect before PROIV was invoked.
Executes the external command or subroutine.
Resets terminal connection characteristics to those required by PROIV.
Schedules the screen to be redrawn prior to the next PROIV input field.
The resetting of terminal connection characteristics may cause input that the user has already typed, but which has not yet been accepted, to be lost.
The screen is not cleared. This must be done by the external routine if required.
Output from the external routine is not under PROIV control and so PROIV features such as report-to-screen paging cannot be applied to it.

If you are only providing the cstubs.c module (using the extsub routine provided), the procedure allows for up to ten external subroutines. The names provided to call the subroutine in the LINK or LINK-CRT statement are:

sub0
sub1
sub2
.
sub9

The names of the subroutines to be called (the names of the subroutines provided in cstubs.c) should be:

sub0( )
sub1( )
sub2( )
.
sub9( )

You must provide the cstubs.c module to enable procedural language interfaces. You only need to provide the extsub.c module if you want to do any of the following:

Change the names used in the LINK or LINK-CRT statement to call the external subroutines.
Change the names of the called subroutines themselves.
Allow for more than ten external subroutines to be called.
Pass more arguments to external subroutines.
A maximum of 255 subroutines can be supported.
Subject to compiler restrictions, a maximum of 256 arguments can be used when calling external subroutines from LINK or LINK-CRT. The default is 10.
Because each parameter is derived from a PROIV string format, the maximum size possible for a parameter is 255 characters excluding the null terminator. In addition to the null terminator, the length of each external subroutine parameter string, is available in the byte position preceding the string itself.

Comment on this topic

Topic ID: 720030