HP 3000 Manuals HP 3000 Manuals
Appendix D Architected Call Interface (ACI)
Introduction
The Architected Call Interface (ACI) allows you to call existing
Transact/iX subprograms from COBOL or Pascal.
ACI is provided as a single intrinsic call. It provides a means of
invoking the desired Transact/iX system and then returning a status value
that indicates the success or failure of the call. It also allows data
to be passed by reference to the Transact/iX subprogram. These
subprograms must reside in an executable library (XL) that has been
provided with the RUN command.
Transact/iX subprograms must be compiled with the subprogram compiler
option.
Syntax
TL_CALL_TRANSACT(program_name, data_buffer, data_length, return_status)
Parameters
program_name Character array by reference
Contains the name of the Transact/iX program to call (as
specified in a SYSTEM statement). The program name can
be uppercase or lowercase, but must be terminated with a
blank. (A program name entered in lowercase will be
automatically changed to uppercase prior to executing the
call.) Because program names cannot be longer than six
characters, the return_status parameter will return a
non-zero value if the name is too long. It will also
return a non-zero value if the program name cannot be
found in the program's execution path.
data_buffer User defined structure by reference
Provides a data passing method to and from the
Transact/iX subprogram and the calling program. This
parameter is similar to the DATA= option in the CALL
verb. The called program will start listing items at the
beginning of this structure. Data can be passed down to
the Transact/iX program by placing data in this structure
prior to the intrinsic call. All items listed in the
Transact/iX subprogram must be declared in this structure
whether or not any data is to be shared. A series of
appropriate LIST statements in the Transact/iX code will
then allow you to interpret the data in this structure.
Any modification of this data in the Transact/iX
subprogram causes this structure to be directly modified
in the calling program's data area.
NOTE If the data buffer of the calling program is NOT defined exactly as
the Transact/iX subprogram's data register, an error message, such
as DATA MEMORY PROTECTION TRAP, is issued and the program
terminates.
data_length 32-bit signed integer by value
The number of bytes in the data_buffer parameter, which
is also the maximum data register size (in bytes) for the
Transact/iX subprogram. This parameter takes precedence
over any DATA= data_length specifications in the
Transact/iX subprogram.
________________________________________________________
NOTE When another language or third party package calls
a Transact/iX subprogram, the data register space
allocated to the subprogram is determined by the
data_length parameter, not the DATA= data_length
option of the SYSTEM statement in the called
program. However, the data_count on the DATA=
option is still observed.
The DATA= data_length option of the SYSTEM
statement and the data_length parameter differ in
how they are declared. The DATA= data_length is
declared in 16-bit words; the data_length parameter
is declared in bytes.
________________________________________________________
return-status 32-bit signed integer by reference
Is used to test the success or failure of the intrinsic
call. This parameter is set to the following:
-2 One or more errors occurred in the called
program other than the following errors:
* Data entry errors for interactive
programs.
* Errors processed by the subprogram
using the STATUS option or the
ERROR= option.
-1 Abnormal end. A nonrecoverable error
occurred while calling the Transact/iX
subprogram.
0 Successful execution of the call to a
Transact/iX subprogram.
1 The call failed because the program_name
parameter contained a program name that
was too long or not terminated with a
blank.
2 The call failed because the program_name
parameter contained a program name that
could not be found in the execution path
of the program file. The Transact/iX
subprogram was either not put in the user
XL or the XL was not included in the RUN
statement.
3 Internal error. A problem arose from
hpgetprocplabel or hpmyprogram intrinsic.
Data Area Allocation
There are a few requirements for the data_buffer parameter that the
calling program must address. It must allocate the entire Transact/iX
data register in the calling program before the call. The data buffer
must be at least as large as the data register used in the subprogram.
If the buffer is smaller than the amount of bytes that are placed in the
LIST and DATA register in the called Transact/iX subprogram, an error
message will be issued in the subprogram.
The values placed in the data buffer by the calling program must ensure
that the formats are correct for Transact/iX as listed in Table 3-3 in
Chapter 3. Values placed in the data_buffer by the calling program
should be double byte-aligned (16-bit) or the values will not be
interpreted correctly by the called Transact/iX code.
The data_length parameter should be the same (or larger) as the size of
the data_buffer.
Database and File Handling
When you call a Transact/iX subprogram, all the databases and files
specified in the SYSTEM statement will be opened, regardless of whether
or not they are accessed by the calling program.
When you call a Transact/iX subprogram, a new process is created for that
subprogram. Because the Transact/iX subprogram and the calling program
are two distinct processes, only the data_buffer is shared between the
two processes. This intrinsic cannot preserve any database or file
information during the call to the Transact/iX subprogram, such as
current record numbers. The calling program has sole responsibility for
managing these issues.
VPLUS Forms
When the called Transact/iX subprogram uses VPLUS forms, the calling
program must ensure that the terminal is in character mode. The VPLUS
comarea is not available to the Transact/iX subprogram when it is called
from a program written in a different language. The Transact/iX
subprogram always assumes that the terminal is in character mode and
returns the terminal to character mode after finishing execution.
Trap Handling
During the invocation of the ACI call, arithmetic trapping is enabled for
the Transact/iX subprogram with calls to HPENBLTRAP, XARITRAP, and
XLIBTRAP. On returning from the called system, the arithmetic trapping is
reset to the state it was in prior to calling the Transact/iX subprogram.
You should keep in mind that the trap handling in the Transact/iX
subprogram may not be the same as the trap handling in the main program.
Examples
The following examples illustrate how ACI can be used to call a
Transact/iX subprogram from a Pascal program and from a COBOL program.
Pascal Code.
program pastest(output);
$standard_level 'OS_FEATURES'$
type
system_name_type = packed array[1..7] of char; {system name plus blank}
nibble = 0..15; {for P types }
data_record = packed record {Data register}
x_item : packed array[1..8] of char; {X(8) }
i4_item : integer; {I(9) }
i2_item : shortint; {I(4) }
nine_item : packed array[1..6] of char; {9(6) }
j4_item : integer; {J(9) }
r4_item : real; {R(6) }
packed_item: packed array[1..6] of nibble; {P(5) }
filler : packed array[1..2014] of char; {Rest of Data reg. used}
end; {by called subprogram. }
var
data_buffer : data_record;
return_status : integer;
system_name : system_name_type;
procedure tl_call_transact
(
var system_name : system_name_type;
data_buffer : localanyptr;
data_length : integer;
var return_status: integer
); external;
begin
system_name := 'SYS1 ';
with data_buffer do
begin
x_item := 'ABCDEFGH';
i4_item := 12345;
i2_item := 321;
nine_item := '111111';
j4_item := 2222;
r4_item := 99.12;
packed_item[1] := 5;
packed_item[2] := 5;
packed_item[3] := 5;
packed_item[4] := 5;
packed_item[5] := 5;
packed_item[6] := 12; {C - sign bit}
end;
tl_call_transact(system_name,
addr(data_buffer),
sizeof(data_buffer),
return_status);
if (return_status <> 0) then
writeln ('Error calling TRANSACT/iX, Error Number:',return_status);
end.
Pascal Commands.
This code can be compiled into a main program and executed with the
following commands:
:pasxllk pastest
:run $oldpass;xl='userxl'
This runs the above Pascal application PASTEST, which calls the
subprogram SYS1 that resides in USERXL.
COBOL Code.
IDENTIFICATION DIVISION.
PROGRAM-ID. COBTEST.
AUTHOR. HEWLETT-PACKARD.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 SYSTEM-NAME PIC X(7).
01 RETURN-STATUS PIC S9(5) COMP SYNC.
01 DATA-BUFFER.
03 X-ITEM PIC X(8).
03 I4-ITEM PIC S9(5) COMP.
03 I2-ITEM PIC S9(4) COMP.
03 NINE-ITEM PIC X(6).
03 J4-ITEM PIC S9(5) COMP.
03 R4-ITEM PIC S9(5) COMP.
03 PACKED-ITEM PIC S9(5) COMP-3.
03 FILLER PIC X(2018).
01 DATA-LENGTH PIC S9(5) COMP SYNC.
PROCEDURE DIVISION.
MAIN-PROGRAM.
MOVE "SYS1 " TO SYSTEM-NAME.
MOVE 2048 TO DATA-LENGTH.
MOVE "ABCDEFGH" TO X-ITEM.
MOVE 12345 TO I4-ITEM.
MOVE 321 TO I2-ITEM.
MOVE "111111" TO NINE-ITEM.
MOVE 2222 TO J4-ITEM.
MOVE 55555 TO PACKED-ITEM.
CALL "TL-CALL-TRANSACT" USING
SYSTEM-NAME,
@DATA-BUFFER,
\DATA-LENGTH\,
RETURN-STATUS.
IF RETURN-STATUS IS NOT ZERO THEN
DISPLAY "Error calling TRANSACT/iX, Error Number: "
RETURN-STATUS.
STOP RUN.
COBOL Commands.
This code can be compiled into a main program and executed with the
following commands:
:cob85xlk cobtest
:run $oldpass;xl='userxl'
This runs the above COBOL application COBTEST, which calls the
Transact/iX subprogram SYS1 that resides in USERXL.
Pascal Code With Status.
The following example shows how to include the status for the execution
of the Transact/iX subprogram. This example uses a different data
structure from the previous examples, but it can be compiled and executed
in a similar way.
program pastest2(output);
$standard_level 'OS_FEATURES'$
type
system_name_type = packed array[1..7] of char; {system name plus blank}
data_record = packed record {Data register}
tstatus : integer; {I(9) }
x_item : packed array[1..8] of char; {X(8) }
i4_item : integer; {I(9) }
end;
var
data_buffer : data_record;
return_status : integer;
program_name : program_name_type;
procedure tl_call_transact
(
var system_name : system_name_type;
data_buffer : localanyptr;
data_length : integer;
var return_status: integer
); external;
begin
system_name := 'SYS2 ';
with data_buffer do
begin
tstatus := 0;
x_item := 'ABCDEFGH';
i4_item := 12345;
tl_call_transact(system_name,
addr(data_buffer),
sizeof(data_buffer),
return_status);
if (return_status <> 0) then
writeln ('Error calling TRANSACT/iX, Error Number:',return_status);
if (tstatus <> 0) then
writeln ('Error during execution of TRANSACT/iX program:',tstatus);
end;
end.