The function Interface Object Generation provides the option to generate single interface objects online on a separate screen. You either type in the parameter definitions required or read them in from an existing subprogram or a parameter data area (PDA).
Generating an interface object from a PDA saves you the effort of creating a subprogram and defining an inline parameter data area.
This section covers the following topics:
Interface objects are generated into the current Natural library in the
current system file. Therefore, we strongly recommend that you log on to the application
library (or one of its steplibs) used by the client at execution time of the remote
CALLNAT
.
Important:
The function Interface Object Generation
overwrites any data contained in the source work area. When you invoke the function, a
corresponding message will warn you not to delete any existing data unintentionally:
choose PF12 to cancel or choose ENTER to confirm the action and
overwrite the contents of the source work area.
To generate a single interface object
Before you invoke the SYSRPC utility, consider the following:
Log on to the library into which you want to generate the interface object.
If you generate an interface object from a PDA: Rename or copy the PDA from
which you want to generate the interface object if there are objects on the
client side that still reference this PDA. The new name of the PDA must be
identical to the name of the remote CALLNAT
program.
In the Code field of the Client Maintenance menu, enter the following command:
IG
Choose ENTER.
The Generate Interface Object screen appears.
In the Program Name field, enter the name of the interface object to be generated.
The name of the interface object must be identical to the name of the remote
CALLNAT
program.
The Library field is preset to the name of the current library and cannot be changed.
In the Compression field, enter compression type
0
, 1
or 2
(default is 1
); see
Using
Compression described in Operating a Natural RPC
Environment in the Natural RPC (Remote Procedure Call)
documentation.
Choose ENTER.
If the name entered in the Program Name field corresponds to the name of an object that already exists in the assigned library, a window appears with an appropriate message:
Enter an N
(No) and choose ENTER if you want to cancel
the operation. You will return to the Client Maintenance
menu.
Or:
Enter a Y
(Yes) and choose ENTER if you
want to continue with generating interface objects.
If the specified name is identical to a cataloged object of the type subprogram or PDA, the parameter definitions of the respective subprogram or PDA are displayed on the Interface Object Generation screen.
If the specified name is identical to an already generated interface object for
which also a source object exists, all field attributes (see also Specifying
Parameters) are retained. Otherwise, all field
attributes are set to M
(modifiable).
If the string entered in the Program Name field, does not match the name of an object that already exists in the assigned library, an empty Interface Object Generation screen is displayed.
On the Interface Object Generation screen, add or modify the parameters to be used in the interface object as described in Specifying Parameters.
The commands provided on the Interface Object Generation screen are described in Commands for Interface Object Generation below.
Choose ENTER to generate the interface object and to exit. The interface object is generated into the assigned library.
The SYSRPC - Information window appears which indicates the size the interface object requires for sending data from the client to the server or vice versa. The size includes internal RPC information used for the interface object. The indication of the size helps you configure the middleware layer used; for example, the Broker attribute file when EntireX Broker is used.
The following message appears in the SYSRPC - Information window when you generate an interface object from the example subprogram TESTS5 (see Example 1 below):
Interface Object TESTS5 is generated in library SAGTEST (99,49). It requires: Send length: 2249 bytes Receive length: 2221 bytes
If dynamic parameters, X-arrays or X-group arrays are used, this message only
indicates the minimum length requirements. The actual length requirements can only
be determined during program execution and may be different from call to call. If
the Send length
or the Receive length
exceeds the Entire
Net-Work limit of 32000 bytes, a window appears with a corresponding warning:
Enter a Y
(Yes) to continue, or an N
(No) to cancel the
generation. If you enter a Y
, this setting is kept for the entire
SYSRPC session, that is, you can continue generating interface objects without
receiving further warnings.
If the total data (without internal RPC information) sent or received exceeds the limit of 1073739357 bytes (which is 1 GB minus 2467 bytes of internal RPC information), SYSRPC stops processing and issues a corresponding error message. This error message displays the subtotal of the data in bytes that could be transferred at the field up to which the subtotal was calculated. The corresponding field is then marked. In this case, reduce the amount of data before you continue the generation.
If the interface object was generated in the Natural system library SYSRPC, you have to move it to the application library or steplib using the Natural transfer utility SYSMAIN or the Object Handler. Note that you may have to recatalog the source of the interface object in the target environment.
In the input fields provided on the Interface Object Generation screen, you can enter the parameter definitions that are used in the interface object. You can specify a maximum of 5000 parameters. Unless indicated in the table below, input in the fields is mandatory.
Field | Description |
---|---|
Level |
The level of the field. A level can be a number in the range from See also Defining Groups and Example 2 for an example of a group definition. |
Attr |
The attribute of the parameter:
Parameters assigned a level number of If an interface object has been generated from a subprogram or
from a PDA, the attribute is If an interface object has been generated from another interface object, the attribute values specified for the original object are retained. The generated interface object contains a comment that indicates the attribute
specified for the parameter: |
Type |
A Natural data format such as For a description of Natural data formats, see Format and Length of User-Defined Variables and Special Formats in the section User-Defined Variables in the Programming Guide. |
Length |
The length of the parameter or This field does not apply to the following Natural data formats: The Natural data format
|
Prec |
Only applies to Natural data formats The precision of the parameter, that is, the number of digits after the decimal point. |
Dimension 1/2/3 | Only applies to arrays. Optional.
The first, second and third dimension of the parameter. An X-array or an X-group array is specified by entering an asterisk (*) for a dimension. See also Defining X-Arrays and X-Group Arrays. |
This section contains information on:
You only need to define a group structure for a client Natural object that calls a non-Natural object located on an EntireX RPC server. The group structure must correspond to the IDL definition in EntireX (see Special Considerations for Calling EntireX RPC Servers). A group structure is not required for a client Natural object that calls a subprogram located on a Natural RPC server.
Group arrays and X-group arrays passed from a client Natural object to an interface object must be contiguous. Therefore, we strongly recommend that you always pass a complete array to the object by using asterisk (*) notation for all dimensions. We also strongly recommend that you use identical data definitions in the client Natural program, the interface object and the server program.
See also Example 2 for an example of a group definition.
If any dimension of a parameter is extensible, all other dimensions of the parameter are also extensible. If you define extensible and fixed dimensions for a parameter in a subprogram, the Interface Object Generation function issues a warning and automatically changes the fixed dimension to an extensible dimension as demonstrated in Example 3. In a group structure, you can define either an extensible or a fixed dimension for each level. There is no automatic change of a fixed dimension to an extensible dimension between levels.
Natural RPC only supports extensible upper bounds. All X-arrays and X-group arrays in
the generated DEFINE DATA PARAMETER
area of the interface object are
therefore defined as (1:*)
.
Warning: If you generate an interface object from a subprogram or a PDA that contains an X-array or X-group array with an extensible lower bound, the extensible lower bound will be converted to an extensible upper bound. |
For an example of a group with an extensible dimension, see Example 3.
If you want to use reliable RPC and your parameter definitions do not contain group
structures, you have to set COMPAT IDL
before generating the interface
object.
The attribute definitions on the Interface Object Generation screen reflect the perspective of the client. Conversely, the parameter direction in the IDL definition reflects the perspective of the server. This means:
OUT
on the Interface Object Generation screen
corresponds to IN
in the IDL definition.
IN
on the Interface Object Generation screen
corresponds to OUT
in the IDL definition.
If you want to call an EntireX RPC server and the parameter definitions on the Interface Object Generation screen contain group structures, group structure and attribute definitions on the Interface Object Generation screen must correspond to the group structure and parameter direction in the IDL definition.
If you want to call an EntireX RPC server and the corresponding IDL file does not
contain group structures, it is recommended to set COMPAT
IDL
before generating the interface object. In this case,
the attribute definitions on the Interface Object Generation screen
must correspond to the parameter direction in the IDL definition.
This section contains information on the commands provided on the Interface Object Generation screen:
The line commands provided on the Interface Object Generation screen can be used to copy, move, or delete single or multiple lines that contain field values.
Enter a line command at the beginning of a line, that is, overwrite the sequential number and choose ENTER.
See also To copy or move a block of lines and the direct
command RESET
.
Line Command | Function |
---|---|
A
|
Copies or moves the block of lines marked with
CC or MM below the line
in which the command was entered.
|
CC
|
Marks the block of lines to be copied. |
D
|
Deletes the marked line. |
DD
|
Marks and deletes a block of lines.
Mark a block of lines by entering this command in the first and the last line of the block and choose ENTER to execute the command. |
I
|
Inserts five empty lines below the line in which the command was entered. The level is filled with the number of the input field above. |
MM
|
Marks the block of lines to be moved. |
P
|
Copies or moves the block of lines marked with
CC or MM above the line
in which the command was entered.
|
To copy or move a block of lines
At the beginning of the line where the block starts, overwrite the sequence number with either of the following line commands:
CC
to copy the block or
MM
to move the block.
At the beginning of the line where the block ends, overwrite the sequence number with either of the following line commands:
CC
to copy the block or
MM
to move the block.
Choose ENTER.
The line commands disappear, the sequence numbers are displayed again and the block of lines has been marked.
At the beginning of the line below or above which you want to place the marked block of lines, enter either of the following line commands:
A
to copy or move the block below the specified line or
P
to copy or move the block above the specified line.
Note that you can only execute A
or
P
on lines where at least one field is filled.
Choose ENTER.
The block of lines is copied or moved below or above the specified line.
The following direct commands can be entered in the Command line of the Interface Object Generation screen and/or are provided as PF keys:
Local Command | PF Key | Function | |
---|---|---|---|
COMPAT
|
IDL | Generate an interface object according to IDL requirements. | |
NONE | Generate an interface object according to Natural requirements. | ||
void | Show COMPAT setting. | ||
Note: |
|||
LIMIT
|
32000 | Sets the upper size limit to 32000 bytes. | |
1GB | Sets the upper size limit to 1 GB. | ||
void | Removes a size limit set with LIMIT 32000 or LIMIT 1GB. | ||
RESET
|
Removes the line marks set with a line command as described in Line Commands. Note that if lines have been marked incorrectly, an appropriate message
occurs and you have to remove the erroneous line command before you enter
|
||
PF1 | Invokes the editor online help. | ||
PF3 | Exit. Prompts you to save modifications and exit the Interface Object Generation screen. | ||
-H
|
PF5 | Scrolls half a page backward/forward. | |
+H
|
PF6 | ||
-P
|
PF7 | Scrolls one page backward/forward. | |
+P
|
PF8 | ||
TOP
|
PF9 | Scrolls to the beginning of the list. | |
BOT
|
PF10 | Scrolls to the end of the list. | |
CANCEL
|
PF12 | Exits the Interface Object Generation screen without saving any modifications. |
This section provides examples of Natural subprograms and the interface objects generated from them.
The parameter definitions indicated below are extracted from example subprograms, which are supplied in the Natural system library SYSRPC.
The following DEFINE DATA PARAMETER
area (example subprogram TESTS5) shows
four modifiable parameters and the corresponding parameter definitions on the Interface Object Generation
screen:
DEFINE DATA PARAMETER 01 #IDENTIFIER (A10) 01 #N-OF-ID (I4) 01 #FREQ (P5.2) 01 #A100 (A100/5,4)
Interface Object Generation | ||||||||
---|---|---|---|---|---|---|---|---|
Level | Attr | Type | Length | Prec | Dimension 1 | Dimension 2 | Dimension 3 | |
1 | 01 | M | A | 10 | ||||
2 | 01 | M | I | 4 | ||||
3 | 01 | M | P | 5 | 2 | |||
4 | 01 | M | A | 100 | 5 | 4 |
The following DEFINE DATA PARAMETER
area (example subprogram TESTS6) shows
a nested group structure and the corresponding parameter definitions on the Interface Object Generation
screen:
DEFINE DATA PARAMETER 01 GROUP-1(10) 02 A (A20) 02 B (A20) 02 GROUP-2(20) 03 C (A10/5) 03 D (A10) 01 LINE (A) DYNAMIC
Interface Object Generation | ||||||||
---|---|---|---|---|---|---|---|---|
Level | Attr | Type | Length | Prec | Dimension 1 | Dimension 2 | Dimension 3 | |
1 | 01 | M | G | 10 | ||||
2 | 02 | M | A | 20 | ||||
3 | 02 | M | A | 20 | ||||
4 | 02 | M | G | 20 | ||||
5 | 03 | M | A | 10 | 5 | |||
6 | 03 | M | A | 10 | ||||
7 | 01 | M | A | DYNAMIC |
The following DEFINE DATA PARAMETER
area (example subprogram TESTS7) shows
a nested group structure with extensible dimensions and the corresponding parameter
definitions on the Interface Object
Generation screen.
DEFINE DATA PARAMETER 01 GROUP-1(10) 02 A (A20) 02 B (A20) 02 GROUP-2(0:*) 03 C (A10/5) 03 D (A10) 01 LINE (A) DYNAMIC
Interface Object Generation | ||||||||
---|---|---|---|---|---|---|---|---|
Level | Attr | Type | Length | Prec | Dimension 1 | Dimension 2 | Dimension 3 | |
1 | 01 | M | G | 10 | ||||
2 | 02 | M | A | 20 | ||||
3 | 02 | M | A | 20 | ||||
4 | 02 | M | G | * | ||||
5 | 03 | M | A | 10 | 5 | |||
6 | 03 | M | A | 10 | ||||
7 | 01 | M | A | DYNAMIC |