HP 3000 Manuals HP 3000 Manuals
PROC
Calls a procedure that has been placed into a segmented library file (SL)
for Transact/V or compatibility mode. PROC also calls procedures from an
executable library (XL) for native mode programs on Transact/iX.
Syntax
PROC procedure-name [(parameter-list)][,option-list];
Transact/V
PROC calls an MPE system intrinsic or other compiled procedure that is
resident in an SL file. SL files are searched and procedures and
intrinsics are dynamically loaded in the following order: logon group
SL, logon account SL, system SL.
The PROC statement does not directly support intrinsics with an optional
number of parameters (Option Variable Intrinsics); you may call such
intrinsics by using a bit map to specify the parameters you want passed.
Bit maps are always required for any PROC call to an option variable
intrinsic or user defined procedure. They are passed by value as the
last parameter in a parameter list. A bit map is formed by setting a
string of bits to one or zero, depending on whether a parameter is passed
or not passed, respectively. The bit string is then right-justified in a
16- or 32-bit word (depending on the number of possible parameters) and
converted into an integer value. This value is passed to the option
variable procedure as the last parameter. See the SPL Reference Manual
for more information on Option Variable bit maps.
All system intrinsics called can be declared in a DEFINE(INTRINSIC)
statement. When this is done, the intrinsics are resolved only from the
system SL.
Transact/iX
The Transact PROC verb is the same, in effect, under MPE V and MPE/iX. It
is used to call procedures written in other languages. The primary point
to be aware of is that both Transact subprograms and routines written in
other languages must reside in an executable library (XL) or be linked
into your program if they are to be called by a Transact program under
MPE/iX. Switch routines must be written for any user defined subroutines
running in compatibility mode, including all SPL routines.
Two features, the PROCALIGNED_16/32/64 compiler options and the %n
alignment options, allow you to tune applications with respect
to the overhead needed for calling external procedures. The
PROCALIGNED_16/32/64 compiler options are discussed in detail under
"Transact/iX Compiler Options" in Chapter 9. The parameter alignment
options are described later in this section.
A third feature, the PROCINTRINSIC compiler option, is designed to ease
the migration of programs that call system intrinsics. Compiler options
are discussed in Chapter 9.
Another item to note is that no conversion between IEEE real and HP real
is attempted. When passing parameters or data that access real numbers,
the called procedure or intrinsic must be compiled with the same real
number format as the main program. (See "Floating Point Formats" in
Appendix B.)
Statement Parts
procedure-name The name under which the procedure is listed in SL or
XL.
parameter-list The items in the parameter-list specify one or more
variables that are passed between the Transact program
and the external procedure. The list can contain any
number of variables, separated by commas. The order in
which you place the variables is determined by the order
in which the called procedure expects them. The only
exception is that a function return variable can be
placed anywhere in the list; a function return variable
is indicated by a preceding "&".
The following special characters can precede any
parameter:
% Passes the given parameter by byte address (by
reference)
# Passes the given parameter by value rather than by
reference
& Copies the function value returned by the intrinsic
to the field in the data register associated with
the given item, or to the status register. Only
one such designated parameter can be included in
the parameter-list, and it can appear anywhere in
the list.
The default (no special character) passes a parameter by
word address.
You can indicate to the called procedure the existence
of a null parameter by placing consecutive commas on the
list. Transact passes a 16-bit value of zero for this
null parameter. Use two commas if the parameter has a
32-bit value, and is passed by value. Use one comma if
the parameter is passed by reference.
All addresses specified by the items in parameter-list
are 16-bit addresses. If you want to specify a byte
address, precede the item-name with "%". For example,
ITEM(NUM) specifies a 16-bit address, whereas %ITEM(NUM)
specifies a byte address. PROC does not automatically
align data parameters on 16-bit boundaries.
_______________________________________________________
NOTE Transact does not verify that parameters are
correctly set up. You must verify this before
attempting to call a procedure.
_______________________________________________________
The parameter-list may consist of any of the following:
(item-name Address of a logical array
[(subscript)]) containing the value of an item in
the data register. Use this
parameter to pass any values defined
in your program. It is up to you to
make sure that the item is on a
16-bit boundary in the data register
if you want to pass a 16-bit
address. The beginning of the data
register is on a 16-bit boundary; if
you add items with an odd number of
bytes, you should add a dummy fill
character to retain 16-bit
boundaries.
You can include any of the following key words in a
parameter-list. If the key word has an argument, it
must immediately follow the key word with no intervening
blanks. Transact supplies a value (usually an address)
whenever it finds one of these key words in a parameter
list.
ARG Address of a logical array
containing the argument value
currently associated with the key
for data set or file operations.
ARGLNG Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the argument value.
BASE[(base-name)] Address of a logical array
containing the name of the given
database preceded by the
two-character base-id supplied by
the database, and followed by a
blank character. If no base-name is
specified, then the home base is
assumed. Note, the home base cannot
be specified.
BASELNG Address of a 16-bit integer
[(base-name)] (I(5,,2)) containing the byte length
of the given base-name, including
the terminating blank.
BYTE(item-name) Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the value of the given item.
COUNT(item-name) Address of a 16-bit integer
(I(5,,2)) containing any subitem
occurrence count for the given item.
A value of 1 means that the given
item is not a compound type
containing subitems.
DECIMAL Address of a 16-bit integer
(item-name) (I(5,,2)) containing the decimal
place count for the given item.
FILEID(file-name) Address of a 16-bit integer
(I(5,,2)) containing the identifier
assigned to file-name by MPE when
the file was opened by this process.
The following special files can also
be used in conjunction with the
FILEID parameter:
TRANIN Transact input file
TRANOUT Transact output file
TRANLIST Transact printer
output file
INPUT Address of the logical array
containing the value that was last
input in response to an INPUT
statement prompt.
INPUTLNG Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the input value.
ITEM(item-name) Address of a logical array
containing the name of the given
item.
ITEMLNG Address of a 16-bit integer
(item-name) (I(5,,2)) containing the byte length
of the given item name.
KEY Address of a logical array
containing the name of the data item
currently used as a key for data set
or file operations. The data item
name must be terminated by a
semicolon (;).
KEYLNG Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the data item name in the key,
including the terminating semicolon.
POSITION Address of a 16-bit integer
(item-name) (I(5,,2)) containing the position
(the byte offset) of a child item
within its parent item. This
parameter is set to -1 to indicate
that there is no parent item.
SET(set-name) Address of a logical array
containing the name of the given
data set followed by a blank.
SETLNG(set-name) Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the given data set name,
including the terminating blank.
SIZE(item-name) Address of a 16-bit integer
(I(5,,2)) containing the byte length
of the display or entry format for
the given item.
STATUS Address of the lower order 16-bits
of the 32-bit status register set by
Transact. If the STATUS parameter
is NOT used, then the 32-bit status
register is set to one of the
condition codes generated by the
called procedure (CCL, CCE, or CCG).
Condition codes are defined as
follows:
CCL = -1
CCE = 0
CCG = +1
Condition codes in the status
register can be tested with a
subsequent IF statement. For
example:
IF STATUS < 0 THEN GO TO CCL-PROCESS;
where CCL-PROCESS will handle a CCL
condition.
Upon exiting from the PROC, the
entire 32 bits of the status
register is set to the value in the
lower order 16 bits of the status
register.
STATUS(DB) Address of the condition word block
returned by the database. (The
discussion of MOVE explains how to
use this value.)
STATUS(IN) Address of a 16-bit integer
(I(5,,2)) containing the STATUS
value following the most recent user
input statement (PROMPT, DATA, or
INPUT). (See the appropriate verb
for the interpretation of the STATUS
value.)
TYPE(item-name) Address of a 16-bit integer
(I(5,,2)) containing a code that
represents the data type of
item-name. The code represents the
data type by its position in the
sequence: X, U, 9, Z, P, I, J, K,
R, E, @; thus, the code corresponds
to a data type as follows:
0=X, 1=U, 2=9, 3=Z, 4=P, 5=I, 6=J,
7=K, 8=R, 9=E, and 10=@ (the marker
item)
VCOM(form-file) Address of the logical array
containing the VPLUS communication
area being used for the referenced
form-file. (See the discussion of
the VPLS option under SET (OPTION)
in this chapter.)
option-list One or more of the following options can follow the
parameter list, separated by commas:
UNLOAD (This option is for
Transact/V only.) Unloads
the procedure being called
following execution; that is,
removes it from the Loader
Segment Table. By default,
Transact leaves an entry in
the Loader Segment Table for
each called procedure after
it executes. Only use this
option if you do not need the
procedure again. Otherwise,
Transact incurs extra
overhead loading the
procedure the next time it is
called.
For Transact/iX, all
procedures are bound at link
time or as a part of the RUN
command. If you use the
UNLOAD option you will get
the compiled message:
INFO: THE `UNLOAD' OPTION FOR THE PROC VERB HAS NO MEANING
ON AN MPE/IX SYSTEM.
NOTRAP Ignores any arithmetic trap
detected in the operation of
the procedure. By default,
Transact issues an error
message and terminates the
called procedure when it
encounters an arithmetic
error.
NOLOAD Loads the called program the
first time it is called
rather than when the program
is initiated. By default,
Transact loads all external
procedures when it initiates
the calling program.
Used in combination with
UNLOAD for Transact/V only,
this option can save Loader
Segment Table space. NOLOAD
is ignored if the called
procedure is an MPE system
intrinsic declared in a
DEFINE(INTRINSIC) statement;
if you want such a procedure
to be loaded dynamically, do
not include it in a
DEFINE(INTRINSIC) statement.
____________________________
NOTE The following option
should not be used with
Transact/iX.
____________________________
language Used to specify the language
in which the procedure is
written: Pascal, COBOL,
FORTRAN, BASIC, or SPL. This
option is needed to call
COBOL procedures to avoid an
arithmetic trap when the
stack exceeds 16K 16-bit
words.
Parameters Passed by Byte Address
An option is available on the PROC verb to specify alignment on
individual reference parameters passed by byte address. This option
takes the form %n, where n can be 8, 16, 32, or 64, as follows:
%8 Align parameter on an 8-bit boundary (this is the default)
%16 Align parameter on a 16-bit boundary
%32 Align parameter on a 32-bit boundary
%64 Align parameter on a 64-bit boundary
The alignment option must precede the parameter affected. For example,
PROC GETNAME (%32(NAME));
This option takes precedence over the PROCALIGNED_16/32/64 options for
the individual parameter. It is only active for the Transact/iX
compiler. Under the Transact/V processor, all parameters passed on a
greater than 8-bit boundary are treated as 16-bit address parameters.
When PROCINTRINSIC is specified, but the alignment check is less than
that required by the intrinsic definition in SYSINTR.PUB.SYS, an error
occurs at run time.
Parameters Passed by Value or by Reference
Transact/V does not check passed parameters to verify that they are of
the same type as the parameters expected by the called procedure. The
Transact/iX compiler checks calls to system intrinsics, verifying that
reference parameters are passed by reference and value parameters are
passed by value. An informational message is reported if a parameter is
not passed in the expected way.
For example, the ASCII intrinsic expects the first parameter to be passed
by value. If, instead, it is passed by reference using the PROC verb,
the Transact/iX compiler issues the following informational messages:
*INFO: PROC PARAMETER 1 WAS PASSED BY REFERENCE WHEN VALUE EXPECTED
*INFO: ERRORS IN PROC PARAMETERS TO 'ASCII' WILL CAUSE A RUN TIME ERROR
At run time, the following error occurs when the PROC ASCII statement is
encountered:
*ERROR: PARAMETER SPECIFICATION ERRORS PREVENTED PROC CALL
Transact/V programs that take advantage of no type checking may require
that you write a procedure to provide the same functionality as the
intrinsic being accessed. For example, since no parameter type checking
is done on calls to user defined procedures, you can code a procedure
which has the same parameters as the intrinsic and which merely calls the
intrinsic. In Transact/iX, you would then use the PROC verb to call this
procedure rather than the intrinsic, passing the parameters in the same
way as when the intrinsic was called directly.
Accessing COBOL Subroutines
When the Transact/iX compiler generates the procedure name in the PROC
statement, hyphens are left standing--they are neither converted to
underscores nor removed. On the other hand, COBOL II/XL converts hyphens
to underscores. Therefore, unless precautions are taken, COBOL II
subroutines that are recognized by Transact/V in compatibility mode will
not be recognized when the subroutine is recompiled using COBOL II/XL and
linked or loaded with a Transact/iX program. To make the names
consistent, you can specify the COBOL II/XL compiler option that removes
hyphens from COBOL subroutine names or you can use underscores instead of
hyphens when naming any COBOL subroutines that will be used under
Transact.
Option Variable Procedures
Since option variable procedures do not exist under MPE/iX, the
Transact/iX compiler only supports calls to option variable intrinsics if
the intrinsic is declared in a DEFINE(INTRINSIC) statement or the
PROCINTRINSIC option is specified in the compile. The bit map, included
as part of the parameter list, is ignored and the remaining parameters
are checked in accordance with their specification in SYSINTR.PUB.SYS. No
implicit type conversions are performed.
User-defined option variable procedures must either be accessed via a
switch to a compatibility mode routine or be converted to fixed parameter
procedures and recompiled with a native mode compiler. The former option
is the only option available to users of SPL procedures who do not want
to recode these routines in a native MPE/iX language.
Null Parameters
Under Transact/iX, all null parameters for option-extensible intrinsics
must be designated by single commas. The Transact/V convention of using
two or four consecutive commas to denote a null 32-bit or 64-bit value
parameter is interpreted by Transact/iX as denoting two or four null
parameters.
One method of getting around this incompatibility is to modify the source
so that all 32-bit and 64-bit value parameters of option-extensible
intrinsics are passed. Another method is to modify the Transact code to
use only single commas in place of 32-bit or 64-bit null value
parameters. However, this method makes the modified source code
incompatible with Transact/V.
Null parameters passed to user defined procedures under Transact/V cause
16-bit zeros to be passed under Transact/iX.
Locating Procedures
Under Transact/V, there are two library search methods for resolving
procedures accessed via the PROC verb. If the procedure name has not
been included in a DEFINE(INTRINSIC) statement, the SL's are searched as
follows: the logon group, the PUB group in the logon account, and
finally, the PUB.SYS group. If the procedure name has been included in a
DEFINE(INTRINSIC) statement, SL.PUB.SYS will be searched. Under
Transact/iX, the libraries and the order in which they are searched must
be specified at either link or run time.
The libraries and the order in which they are searched by processes
CREATED and ACTIVATED by Transact/iX must be specified in the :RUN
command used to run the Transact/iX program. The LIBSEARCH bits on
CREATE and ACTIVATE should be set to "NO" to force the create process to
use the LIBLIST specified on the :RUN command.
Double Buffering Parameters
By default, Transact/iX generates code to double buffer all reference
parameters (parameters passed by address) if they are not preceded by
"%", "#", or "&". The double buffered alignment is determined from
the type and size of the data item passed via the PROC call.
However, since double buffering is inefficient, the compiler options
PROCALIGNED_16/32/64 should be used whenever possible to bypass double
buffering.
Examples
The format of the intrinsic ASCII in the MPE Intrinsics Manual is:
I LV IV BA
numchar:=ASCII(word,base,string);
The PROC verb to call the ASCII intrinsic has the following format:
PROC ASCII (#(WORD),#(BASE),%(STRING),&(NUMCHAR));
WORD, BASE, and STRING are program variables that correspond to the
parameters of the intrinsic and NUMCHAR is a functional return variable
to which the procedure returns the number of characters translated by the
ASCII intrinsic. Note that NUMCHAR is at the end of the PROC parameter
list rather than in its position in the intrinsic definition. WORD and
BASE are preceded by a # symbol because they are passed by value; STRING
is a byte address as indicated by the preceding "%". For additional
examples of the PROC verb, see "Migration Examples" in Appendix B.
The example below calls the VPLUS procedure VPRINTFORM to print a form on
the line printer.
SYSTEM TEST,
VPLS=CUSTFORM; << Form definition in DICTIONARY. >>
DEFINE(ITEM) PRINTCNTL I(2):
PAGECNTL I(2):
:
DEFINE(INTRINSIC) VPRINTFORM;
:
PRINT:
LIST PRINTCNTL:
PAGECNTL;
LET (PRINTCNTL) = 1; << Underline fields >>
LET (PAGECNTL) = 0; << CR/LF off >>
PROC VPRINTFORM (VCOM(CUSTFORM),
(PRINTCNTL),
(PAGECNTL));
Note that Transact supplies the comarea location for the forms file
CUSTFORM automatically through the parameter VCOM(file name).
The MAP parameter sets up a bit map for an intrinsic that is type OPTION
VARIABLE.
The following example calls the intrinsics CREATE and ACTIVATE. (See the
MPE Intrinsics Reference Manual for the syntax of these intrinsics.)
Since both intrinsics are Option Variable, a bit map (MAP) is included at
the end to indicate which parameters to pass. Because this map and the
CFLAG parameter are passed by value, they are preceded by a # symbol.
DEFINE(ITEM) ROUTINE X(20): <<Process name >>
CPIN I(4): <<PIN of process >>
CFLAG I(4),INIT=(BINARY(1000001)):
<<Flags >>
MAP I(4),INIT=(BINARY(1010100000);
<<Bit map for optional parameters >>
$$A:
LIST ROUTINE,INIT:
CPIN,INIT:
CFLAG:
MAP;
DATA ROUTINE("WHICH PROCESS?");
PROC CREATE (%(ROUTINE),,(CPIN),,#(CFLAG),,,,,,#(MAP));
LET (MAP) = 3;
LET (CFLAG) = 3;
PROC ACTIVATE (#(CPIN),#(CFLAG),#(MAP));
END;
The following example shows the use of the FWRITE intrinsic in
conjunction with the Transact terminal output file TRANOUT:
SYSTEM DEMO01;
DEFINE(INTRINSIC) FWRITE;
DEFINE(ITEM) MSG X(30);
DEFINE(ITEM) COUNT I(4);
DEFINE(ITEM) CONTROL I(4);
LIST MSG : COUNT : CONTROL;
MOVE (MSG) = "HELLO THERE WORLD!!";
LET (COUNT) = -19;
LET (CONTROL) = 0;
PROC FWRITE (#FILEID(TRANOUT), (MSG), #(COUNT), #(CONTROL));
The next example calls the database intrinsic DBCLOSE using the BASE,
SET, and STATUS key-word parameters.
SYSTEM TEST, BASE=CUSTOMER ("MANAGER");
DEFINE(ITEM) MODE. I(2);
DEFINE(INTRINSIC) DBCLOSE;
:
LET (MODE) = 5;
PROC DBCLOSE(BASE,
SET(CUST-MAST),
(MODE),
STATUS(DB));
The next example shows a call to DSG/3000 intrinsics. The data register
size is increased because of DSG requirements:
SYSTEM DSG, DATA=4000,10;
DEFINE(ITEM) GRAF 1415 I+(2,,2):
GRAFSIZE I(4,,2):
LANG I(1,,2);
LIST GRAF:GRAFSIZE:LANG;
LET (GRAFSIZE) = 1415;
LET (LANG) = 0;
PROC GINITGRAF((GRAF),(GRAFSIZE),(LANG));
DISPLAY "Return from GINITGRAF";
The next example calls the BRW intrinsic BRWEXEC to execute a report on
line.
SYSTEM TEST;
DEFINE(ITEM) BRW-COMAREA X(300):
RETURN-STATUS I(4) = BRW-COMAREA(1):
ERROR-PARM I(4) = BRW-COMAREA(3);
DEFINE(ITEM) BRW-PARAMETERS X(176):
MAX-NUM-PARMS I(4) = BRW-PARAMETERS(1):
ACTUAL-NUM-PARMS I(4) = BRW-PARAMETERS(3):
PARM-NAME-1 X(20) = BRW-PARAMETERS(5):
PARM-TYPE-1 I(4) = BRW-PARAMETERS(25):
PARMRESULT-TYPE1 I(4) = BRW-PARAMETERS(27):
RESULT-LENGTH-1 I(4) = BRW-PARAMETERS(29):
PARM-MODE-1 I(4) = BRW-PARAMETERS(31):
UPSHIFT-1 I(4) = BRW-PARAMETERS(33):
PARM-VALUE-1 X(55) = BRW-PARAMETERS(35):
RESERVE-1 X(1) = BRW-PARAMETERS(90):
PARM-NAME-2 X(20) = BRW-PARAMETERS(91):
PARM-TYPE-2 I(4) = BRW-PARAMETERS(111):
PARMRESULT-TYPE2 I(4) = BRW-PARAMETERS(113):
RESULT-LENGTH-2 I(4) = BRW-PARAMETERS(115):
PARM-MODE-2 I(4) = BRW-PARAMETERS(117):
UPSHIFT-2 I(4) = BRW-PARAMETERS(119):
PARM-VALUE-2 X(55) = BRW-PARAMETERS(121):
RESERVE-2 X(1) = BRW-PARAMETERS(176);
LIST BRW-COMAREA:
BRW-PARAMETERS;
LET (MAX-NUM-PARMS) = 2;
LET (ACTUAL-NUM-PARMS) = 1;
MOVE (PARM-NAME-1) = "$REPORT";
.
.
.
PROC BRWEXEC((BRW-COMAREA),(BRW-PARAMETERS));
The next example shows a call to the compiler library routine DABS' to
determine the absolute value of a number.
SYSTEM ABSTST;
DEFINE(ITEM) REALVALUE R(8,2,8), INIT=-128.8:
RESULT R(8,2,8), INIT=;
LIST REALVALUE: RESULT;
DISPLAY REALVALUE: RESULT;
PROC DABS'(#(REALVALUE),&(RESULT));
DISPLAY REALVALUE: RESULT;
END;
There are two things to check when using the compiler library:
* Make sure you use the PROCINTRINSIC compiler option for
Transact/iX and the DEFINE(INTRINSIC) statement for Transact/V.
* Verify that all parameter types match the function parameters and
function return.
In addition, be aware that parameters passed by value are preceded by a
"#" (pound sign). The last parameter is the function return and it is
preceded by a "&" (ampersand).
The last example is a Transact program that calls BRW.
Prior to running the program, we used BRW to design a report and compile
the report into a BRW execution file named BRWEXECR. The Transact program
uses VPLUS to present the user with a main menu of options. If the user
enters option 1, the BRW report is executed. The PROC calls result in
the BRW Report Selection menu being displayed with the name of the report
requested already filled in. The user then requests the report the same
as when running BRW directly.
SYSTEM BRW,VPLS=MYFF(MAINMENU(SELECTION));
DEFINE(ITEM) BRW-COMAREA X(106):
BRW-STATUS I(4) = BRW-COMAREA:
BRW-ERROR I(4) = BRW-COMAREA(3):
BRW-COM-LENGTH I(4) = BRW-COMAREA(5):
BRW-EXEC-FILE. X(36)= BRW-COMAREA(7):
BRW-DEFAULTS I(4), INIT=0:
SELECTION I+(1);
LIST BRW-COMAREA:
BRW-DEFAULTS:
SELECTION;
LET (BRW-COM-LENGTH) = 50;
GET(FORM) MAINMENU;
IF (SELECTION) = 1 THEN
DO
PROC BRWINITREQUEST ((BRW-COMAREA));
MOVE (BRW-EXEC-FILE) = "BRWEXECR";
PROC BRWSTARTREQUEST ((BRW-COMAREA),
(BRW-DEFAULTS));
PROC BRWSTOPREQUEST ((BRW-COMAREA));
DOEND;
EXIT;