HP 3000 Manuals

Operation Definitions (Cont.) [ HP RPG/iX Reference Manual ] MPE/iX 5.0 Documentation

HP RPG/iX Reference Manual

Operation Definitions (Cont.)

EXIT

This external subroutine operation executes an external subroutine. When
the subroutine finishes, control returns to the next executable operation
in sequence.

Enter the external subroutine name in the Factor 2 Field. It can contain
up to six characters. Do not use the Factor 1 and Result Fields.
[REV BEG]

The RPG program can share data with the external subroutine in two ways.
If the subroutine is in an XL and will be linked at run time, use the
PARM operation to pass data to and from the subroutine. Enter statements
using the PARM operation, one for each data element you are passing,
immediately after the EXIT operation. If the subroutine is not in an XL,
but is linked directly to your program, subroutines can share data in an
additional way. Data elements can be made global with the RLABL
operation. After a data item is named with the RLABL operation, the data
item is accessible to any subroutine executed by an EXIT operation.
Subroutines in an XL cannot access the global data items named in the
RLABL operation.

Examples

See figure 8-33 for an example of how to use EXIT with PARM. See figure
8-37 for an example of how to use EXIT with RLABL.

The following example shows linking an HP C subroutine SUBSRC directly to
an RPG program named RPGSRC:

:RPGXL RPGSRC, RPGOBJCT
:CCXL SUBSRC, SUBOBJCT
:LINKEDIT
>LINK FROM=RPGOBJCT, SUBOBJCT;TO=RPGPROG
>EXIT
:RUN RPGPROG

The next example shows linking a subroutine that is in an XL. The
subroutine must have data items passed by the PARM operation, not the
RLABL operation.

:CCXL SUBSRC, SUBOBJCT
:LINKEDIT
>BUILDXL SUBXL
>ADDXL FROM=SUBOBJCT;TO=SUBXL
>EXIT
:RPGXLLK RPGSRC, RPGPROG
:RUN RPGPROG; XL="SUBXL"

If the XL is not in your current group and account, fully qualify the
"XL=" option of the run command.[REV END]

EXSR

This internal subroutine operation starts the execution of an internal
subroutine (see figures 8-7 and 8-26) You can enter this operation
anywhere in the program. When the subroutine is finished, control
returns to the operation following EXSR.

Enter the name of the subroutine to execute in the Factor 2 Field. This
name must be defined in the Factor 1 Field of the BEGSR operation in the
subroutine. Do not use the the Factor 1 and Result Fields. You can
conditionally execute EXSR by entering indicators in the Control Level
Field (columns 7-8) and the Indicators Field (columns 9-17).

Example

Figure 8-26 shows two subroutines; one calls another. The subroutine
SUBA starts at line 3 and the subroutine SUBB starts at line 5. In the
main program, SUBA is called at lines 1 and 2. When SUBA is executing,
it calls SUBB. SUBB contains a GOTO operation that branches to the end of
that subroutine (line 6) when indicator 01 is ON. When SUBB finishes,
control returns to the line following the EXSR operation at line 4.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| C . |
| C . |
| 1 C EXSR SUBA |
| C . |
| C . |
| 2 C EXSR SUBA |
| C . |
| C . |
| 3 CSR SUBA BEGSR |
| CSR . |
| 4 CSR EXSR SUBB |
| CSR . |
| CSR ENDSR |
| 5 CSR SUBB BEGSR |
| CSR . |
| CSR 01 GOTO TAIL |
| CSR . |
| 6 CSR TAIL ENDSR |
| |
| |
___________________________________________________________________________________

Figure 8-26. Using One Internal Subroutine to Call Another

FNDJW

This system operation locates a JCW in the system JCW table and returns
its value. This operation uses the system intrinsic FINDJCW.

To use FNDJW, leave the Factor 1 Field blank and enter the name of the
JCW you want to locate in the Factor 2 Field. The name can be contained
in an alphanumeric variable or literal. It must begin with a letter. In
the Result Field, enter the field where you want to store the returned
JCW value. The field must be numeric with no decimal positions.

You must enter at least one indicator in the Resulting Indicators Field
(columns 54-59). When FNDJW is executed, the indicators are set to
indicate the outcome of the operation. If the indicator in the High
Subfield is ON, the JCW was not found. If the indicator in the Low
Subfield is ON, the JCW name that you entered does not begin with a
letter. If the JCW was found and its value returned, the indicator in
the Equal Subfield is turned ON.

FNUM

This system operation obtains the MPE file number for a file and returns
it to the program. FNUM does not use a system intrinsic.

To use FNUM, leave the Factor 1 Field blank and enter the name of the
file in the Factor 2 Field. You can use an alphanumeric literal or a
field name. The file name must be defined in a File Description
Specification. In the Result Field, enter the numeric field where you
want to save the returned file number. The field must be numeric with no
decimal positions. The file number returned is in packed decimal format.
If you pass it to an external subroutine, it is passed in packed decimal
format, not integer format. (Many intrinsics require that the file
number be in binary format. This means that you must convert the number
in the external subroutine before you can use it.)

FORCE

This file operation lets you name the file from which the next record is
selected for processing. The record is selected at the beginning of the
next logic cycle (the FORCE operation is in effect only for that cycle).

You can use FORCE to alter the normal multifile processing sequence. Do
not use FORCE for the first record read by the program.

To use the FORCE operation, enter the name of the file you want to
process next in the Factor 2 Field. Leave the Factor 1 and Result Fields
blank. You can use FORCE at detail time in the main program or in a
subroutine. Do not use FORCE at total time. When you force a file that
is accessed with a RAF, the RAF record is also accessible. When a forced
record is processed, the MR indicator is turned OFF (the forced record is
processed as if it has no matching fields). If end-of-file is
encountered in a forced file, the next record is chosen according to the
normal record selection process.

Example

Figure 8-27 shows how to force the file CFILE. Suppose that a program
processes records from three files, AFILE, BFILE, and CFILE. Also assume
that they are processed in the same order as they are listed. To read a
record from CFILE first, ahead of AFILE, a FORCE operation is used. The
operation is only performed when indicator 09 is ON.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| C 09 FORCECFILE |
| |
| |
___________________________________________________________________________________

Figure 8-27. Using the FORCE Operation

GOTO

This branching operation lets you alter the sequential execution of
Calculation Specification operations. You can skip to any TAG operation
or, if you're within an internal subroutine, you can skip to the ENDSR
operation for that subroutine.

To use GOTO, enter the name (label) of the TAG or ENDSR operation to
which you want to skip in the Factor 2 Field. You can enter indicators
in the Indicators Field (columns 9-17) to condition this operation. Do
not use the Factor 1 and Result Fields.

You can branch within detail-time or total-time operations. You can also
branch from detail-time to total-time operations and vice versa. When
branching from detail to total operations, be very careful that it is
allowed in the RPG logic cycle. Do not branch into or out of an internal
subroutine.

See figure 8-44 for examples on how to use the GOTO operation with the
TAG operation.

IFxx

This structured programming operation performs the associated block of
operations (Do Block) immediately following it if Factor 1 and Factor 2
meet the criteria specified by xx.

Table 8-11. IFxx Operations

End the operations in the Do Block with an END operation. If you're
using ELSE with the IF operation, place the END operation after the last
operation in the ELSE Do Block. If the IFxx condition is not satisfied,
the operations following the ELSE or END operation are executed.

Do not split a Do Block between detail, total, or subroutine operations.
You may branch into or out of a Do Block, but be sure that you understand
what the results will be. Do Blocks can be nested; that is, a Do Block
can be contained within another Do Block as shown below (the maximum
number of levels of nesting is 100).

Begin Level 1 DO Block IFEQ (If equal then do)
.
.
ELSE (Else do)
.
.
Begin Level 2 DO Block DOULT (Do until less than)
.
.
Begin Level 3 DO Block DOWNE (Do while not equal)
.
.
End Level 3 DO Block END
End Level 2 DO Block END
End Level 1 DO Block END

To conditionally execute the IFxx operation, enter one or more indicators
in the Indicators Field (columns 9-17). The indicators condition the
execution of the entire set of IF/ELSE/END Do Blocks.

You can enter a field name or a literal in the Factor 1 and Factor 2
Fields. Numeric fields are aligned by decimal point before they are
compared. Shorter fields are padded with zeros (to the left and right)
to make them the same size. Blanks in numeric fields are treated as
zeros. The maximum numeric field length is 15 digits. Alphanumeric
fields are aligned starting with their high-order (leftmost) characters.
Shorter fields are padded with blanks (on the right) to make them the
same size. If you specified an alternate collating sequence, it is used.

You can compare a numeric field to an alphanumeric field. The numeric
field is temporarily converted to alphanumeric format and the two fields
are compared as if they both were alphanumeric. The numeric field is not
aligned by decimal point before the compare. Negative signs are ignored.
For example, the number -123.45 becomes "12345". To avoid problems when
comparing the numeric field, make sure it does not have decimal places,
is the same length, and is not negative. When you compare a numeric
field to an alphanumeric field, you see this compiler message:

9016I NUMERIC FIELD TEMPORARILY CONVERTED TO ALPHANUMERIC FOR
ALPHANUMERIC COMPARE

Do not use the Result Field or the Resulting Indicators Field (columns
54-59).

Example

Figure 8-28 shows how to use the IFxx and the ELSE operations. The IFEQ
operation in line 1 executes the MOVE operation in line 2 when the field
CODE is equal to zero. If CODE is not equal to zero, the operations in
lines 4 through 5 are executed.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234|
| _______________________________________________________ |
| |
| 1 C CODE IFEQ 0 |
| 2 C MOVE CODE CODE2 |
| 3 C ELSE |
| 4 C SUB SHIFT CODE2 2121 |
| C N21 Z-ADD0 X |
| C . |
| 5 C . |
| C END |
| |
| |
| |
___________________________________________________________________________________

Figure 8-28. Using the IFEQ Operation
[REV BEG]

INTR

This system operation lets you call MPE intrinsics directly from an RPG
program. Specify the name of the intrinsic beginning in the Factor 2
field, continuing through the Result Field (columns 33-48) if necessary.
You can call only intrinsics whose names are 16 characters long or less.

To pass parameters to the intrinsic, follow the INTR operation statement
with an IPARM operation statement for each parameter.

The statements defining the intrinsic call (the INTR statement and its
associated IPARM statements) can be placed anywhere in the calculations,
but they cannot begin in Detail Calculations and continue in Total
Calculations.

If the intrinsic is a function, you can specify a field in Factor 1 to
hold the value returned by the intrinsic. Define the field in columns
49-52 if it has not already been defined. If the intrinsic function
returns a numeric value, you can specify an alphanumeric field in Factor
1. This field will contain alpha-binary data, which is discussed under
the IPARM operation following.

The intrinsic's condition code, indicating the success of the call, is
returned in the Resulting Indicators Field (columns 54-59). In general,
if the intrinsic call is successful, the indicator in columns 58-59 is
turned on; indicators in columns 54-55 (less than) and columns 56-57
(greater than) may indicate the intrinsic call was unsuccessful. Refer
to the MPE/iX Intrinsics Reference Manual for condition codes returned by
each intrinsic.[REV END]

IPARM
[REV BEG]

IPARM is a system operation that allows the RPG program to pass
parameters to an MPE intrinsic specified by the preceding INTR operation.
Specify the parameter to be passed in the Result Field of the IPARM
operation.

RPG uses the intrinsic mechanism to determine the correct parameter type
and calling method. Since RPG stores all numeric fields internally in
packed decimal format, RPG converts IPARM parameters to the proper type
(for instance binary) before calling the intrinsic. If the parameter is
passed by reference, the parameter is converted back to packed decimal
format after the intrinsic call. Refer to the MPE/iX Intrinsics
Reference Manual for more information about intrinsics.

If the parameter is a numeric type, you can specify an alphanumeric field
in the Result Field. The data returned will be alpha-binary data (see
the discussion on alpha-binary data next). This is for single fields
only, not for numeric arrays.

If the intrinsic allows it, and you want to use the default value for a
particular parameter, leave the Result Field blank for that IPARM
operation. If the intrinsic does not require you to specify all the
parameters, you can leave off the parameters after the last required one
is defined.

Alpha-Binary Data

Even though a parameter for an intrinsic may be defined in the MPE/iX
Intrinsics Reference Manual as a numeric data type (i.e. integer,
double, or real), you do not have to assign a numeric field to hold the
data in your RPG program unless you want to use it in an arithmetic
calculation. When you assign a numeric field, RPG automatically converts
the values from binary format (which the intrinsics use) to packed
decimal (which RPG uses).

You can avoid unnecessary data conversions and save processing time by
assigning a numeric parameter to an alphanumeric field in your RPG
program if you do not need to use the field as a number. The numeric
value is stored in the alphanumeric field in its binary bit pattern.
This data representation is called alpha-binary because the alphanumeric
field stores the binary-coded data. Note that output field editing is
not possible with alpha-binary data. Numeric arrays cannot be stored as
alpha-binary data.

Alpha-binary storage is useful when numeric data that is returned from
one intrinsic is passed directly to another intrinsic without being
processed by the RPG program. For example, if you call the CREATE
intrinsic, an integer PIN number is returned. This number is used in
subsequent calls to the ACTIVATE and KILL intrinsics. It is not used in
a numerical calculation, so it does not need to be stored as an RPG
numeric field. Specifying the PIN field as alphanumeric allows the
integer data to pass directly between intrinsics without conversion.

Alpha-binary data is also useful when intrinsic parameters contain bit
fields you need to set or test. With alpha-binary data, you can use the
TESTB, BITON, and BITOF operations to manipulate bit fields.[REV END]

Limitations and Guidelines for Intrinsic Parameters[REV BEG]

For intrinsic parameters specified as 16-bit integers (I16 or U16),
specify an RPG numeric field of 1 to 5 digits with 0 decimal places. For
32-bit integers, specify a numeric field of 6 to 10 digits with 0 decimal
places. RPG/iX does not support 64-bit numeric items because it takes 20
digits to hold an item of this size, and the maximum field size for
RPG/iX is 15. This means, for example, that you cannot access item 64 of
the FFILEINFO intrinsic to retrieve the 64-bit virtual address of the
file.

RPG/iX supports only integral values for floating-point numbers used in
intrinsics. For example, the PAUSE intrinsic can be used to pause for 8
seconds, but not for 8.5. Define RPG fields of 6 to 10 digits with 0
decimal places for parameters defined as 32R.

Make sure the value of the numeric field does not exceed the maximum
value for the parameter. For example, a 5-digit field can contain a
value up to 99,999, but an I16 parameter must stay between -32768 and
32767 to keep from overflowing.

If an intrinsic uses a bit mask for a parameter, you can either pass an
RPG numeric field loaded with a number whose binary bit pattern forms the
bit mask you want (RPG automatically converts the number into binary), or
you can define an alphanumeric field and set the bit pattern with the
BITON and BITOF operations. This applies to single fields only, not to
arrays.

Define numeric and alphanumeric arrays with an Extension Specification.
For numeric arrays, specify zero decimal places.

For intrinsics that accept literals for parameters, first copy the
literal into a field or array of the proper type, then use the field or
array in the Result Field of the IPARM statement.[REV END]

[REV
BEG]

RPG/iX does not support the following:

* intrinsics that require passing pointers to a procedure

* user-supplied addresses of items (RPG/iX determines all reference
addresses)

* parameters defined as sets

Examples

Following are examples of RPG source segments that use the INTR and IPARM
operations to call intrinsics.
___________________________________________________________________________________
| |
| 1 2 3 4 5 6 7 |
| 678901234567890123456789012345678901234567890123456789012345678901234 |
| _______________________________________________________ |
| |
| |
| C* NUMCHR := ASCII(NUM, BASE, STR); |
| C* /* FUNCTION RETURN NUMCHR DEFINED NUMERIC, 4 DIGITS, 0 DEC PLACES */|
| C* |
| C NUMCHR INTR ASCII 40 |
| C IPARM NUM |
| C IPARM BASE |
| C IPARM STR |
| |
| |
| C* WHO(,CAP); /* SKIP THE FIRST PARAMETER */ |
| C* /* ALSO, OPTION EXTENSIBLE */ |
| C INTR WHO |
| C IPARM |
| C IPARM CAP |
| |
| |
| C* BIN := BINARY(ASCI, LEN); /* SETS CONDITION CODE */ |
| C* |
| C BIN INTR BINARY 010203 |
| C IPARM ASCI |
| C IPARM LEN |
| |
| |
| $ALIAS INTNAM = BINARY |
| . |
| . |
| . |
| C BIN INTR INTNAM 010203 |
| C IPARM ASCI |
| C IPARM LEN |
| |
___________________________________________________________________________________

Using the INTR and IPARM operations
[REV END]

Using the INTR and IPARM operations (continued)
[REV END]

MPE/iX 5.0 Documentation