Version 6.3.13 for UNIX	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

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.

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

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

1. Before you invoke the SYSRPC utility, log on to the library into which you want to generate the interface object.

2. In the Code field of the Client Maintenance menu, enter the following command:

   IG

3. Choose ENTER.

   The Generate Client Stub Routine window appears.

4. 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 current library and cannot be changed.

   DBID, FNR are non-modifiable fields that display the database ID (DBID), the file number (FNR) and the type of Natural file (FNAT = system, FUSER = user) for the current library.

   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 Remote Procedure Call (RPC) documentation.

5. 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 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, the parameter definitions of the respective subprogram are displayed on the Interface Object Generation screen.

     If the specified name is identical to an 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 name entered in the Program Name field, does not correspond to the name of an object that already exists in the assigned library, an empty Interface Object Generation screen is displayed.

6. 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 correspond to the commands described in Commands and PF Keys in the section Service Directory Maintenance.

   Exceptions:

   Attribute	Values
   EXPIRATION	Not applicable to interface object generation.
   COMPAT	IDL | NONE | void
   	IDL Generate an interface object according to IDL requirements. NONE Generate an interface object according to Natural requirements. void Show COMPAT setting. Note: See also: Special Considerations for Reliable RPC and Special Considerations for Calling EntireX RPC Servers .
   LIMIT	32000 | 1GB | void
   	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

7. Choose ENTER to generate the interface object and to exit. The interface object is generated in 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 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 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.

The section below contains information on:

• Defining Groups

• Defining X-Arrays and X-Group Arrays

• Special Considerations for Reliable RPC

• Special Considerations for Calling EntireX RPC Servers

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

Warning: Any group definitions in a subprogram will be ignored when an interface object is generated from this subprogram. In this case, you have to define the group again on the Interface Object Generation screen and adapt the dimension of the group elements accordingly. (Dimensions defined within a group are propagated to the parameter definitions at a lower level.) If you generate an interface object from another interface object that contains a group, the group definitions will be retained.

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

Warning: If you generate an interface object from a subprogram 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.

Special Considerations for Reliable RPC

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.

Special Considerations for Calling EntireX RPC Servers

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.

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

Example 2

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

Example 3

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

www.softwareag.com

Copyright © 1992-2012 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT