The function Single Interface Object Generation provides the option to generate single interface objects online on a separate window. You either type in the parameter definitions required or read them in from an existing subprogram.

This section covers the following topics:

• Using the Interface Object Generation Function

• Specifying Parameters

• Examples of Interface Object Generation

---

Using the Interface Object Generation Function

This section provides instructions for generating single interface objects by using the function Single Interface Object Generation.

To generate a single interface object

1. In the SYSRPC - Remote Procedure Call window, from the Tools menu, choose Single Interface Object Generation.

   Or:
   In the SYSRPC - Remote Procedure Call window, press CTRL+F8.

   The Input for Interface Object Generation dialog box appears.

2. In the Name text box, 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.

   If required, in the Library text box, enter the name of the library into which you want to generate the interface object. The text box is preset to the name of the current library.

   DBID, FNR is a non-modifiable text box that displays the database ID (DBID), the file number (FNR) and the type of Natural file (FNAT = system, FUSER = user) for the specified library.

   From the Compression drop-down list box, select 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.

3. Choose OK.

   • If the name entered in the Name text box corresponds to the name of an object that already exists in the specified library, a window appears with an appropriate message:

     Choose Yes if you want to modify existing parameter definitions. If the specified name is identical to a cataloged object of the type subprogram, the Interface Object Generation window appears where the parameters definitions of the respective subprogram are contained in a table. If the specified name is identical to an interface object for which also a source object exists, all field attributes (see also Specifying Parameters) from a previous generation are retained. Otherwise, all field attributes are set to M (modifiable).

     Or:
     Choose No if you want to create new parameter definitions. The Interface Object Generation window appears with empty table cells.

     Note that you can still keep old definitions, even after you have entered new values if you abort execution by choosing Cancel.

   • If the name entered in the Name box does not correspond to the name of an object contained in the specified library, an empty Interface Object Generation window appears.

4. In the Interface Object Generation window, add or modify the parameters to be used in the interface object: Enter a value or select it from a drop-down list box as described in Specifying Parameters.

5. Choose OK to generate the interface object and to exit the Interface Object Generation window.

   A window appears which confirms that the interface object is generated into the specified library. In addition, the window 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 window when you generate an interface object from the example subprogram TESTS5 (see Example 1 below):

   Interface Object TESTS5 is generated in library TEST
      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:

   Choose Y (Yes) to continue, or N (No) to cancel the generation.

   If you choose Y (Yes), 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 generating the interface object.

   If the interface object was generated in the Natural system library SYSRPC, you it object 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.

Specifying Parameters

In the table cells provided in the Interface Object Generation window, 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 boxes is mandatory.

Field	Description
Level	The level of the field. A level can be a number in the range from 01 (highest level) to 99 (lowest level). The leading 0 is optional. See also Defining Groups and Example 2 for an example of a group definition.
Attribute	The attribute of the parameter: M (modifiable - INOUT), O (output - OUT) or I (input - IN). Parameters assigned a level number of 2 or greater are considered to be a part of a group. Parameters within a group must have the same attribute as the immediately preceding group that is assigned one level higher. For nested groups, this is the attribute of the group with the highest level. For an example of a group definition, see Example 2. If an interface object has been generated from a subprogram, the attribute is M by default, which may need modification. 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: IN, OUT or INOUT.
Type	A Natural data format such as N (numeric) and G (group), or K (Kanji). Natural data formats C (attribute control) and Handle are not allowed. 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 DYNAMIC. This field does not apply to the following Natural data formats: D (date), G (group), L (logical) and T (time). The Natural data format A is restricted to 1073739357 bytes, the Natural data format B is restricted to 536869678 bytes. DYNAMIC indicates a dynamic parameter and applies to the Natural data formats A and B.
Precision	Only applies to Natural data formats N (numeric) and P (packed). Optional. 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:

• Defining Groups

• Defining X-Arrays and X-Group Arrays

Defining Groups

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. 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.

Defining X-Arrays and X-Group Arrays

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:*).

For an example of a group with an extensible dimension, see Example 3.

Examples of Interface Object Generation

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.

Example 1

The following DEFINE DATA PARAMETER area (example subprogram TESTS5) shows four modifiable parameters and the corresponding parameter definitions in the Interface Object Generation window:

DEFINE DATA
PARAMETER
  01 #IDENTIFIER  (A10)
  01 #N-OF-ID     (I4)
  01 #FREQ        (P5.2)
  01 #A100        (A100/5,4)

Interface Object Generation
	Level	Attribute	Type	Length	Precision	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

Example 2

The following DEFINE DATA PARAMETER area (example subprogram TESTS6) shows a nested group structure and the corresponding parameter definitions in the Interface Object Generation window:

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	Attribute	Type	Length	Precision	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

Example 3

The following DEFINE DATA PARAMETER area (example subprogram TESTS7) shows a nested group structure with extensible dimensions and the corresponding parameter definitions in the Interface Object Generation window.

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	Attribute	Type	Length	Precision	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