Service Directory Maintenance

The Service Directory Maintenance function is used to maintain a service directory in order to connect the client's calling program to a subprogram on a server.

The service directory information is stored in the NATCLTGS subprogram in the library that is defined with the profile parameter RPCSDIR (see the Parameter Reference documentation). If RPCSDIR is set, the Service Directory Maintenance function references the library specified with RPCSDIR. If RPCSDIR is not set (this is the default), the library where you are logged on is referenced. In this case, log on to the library (or one of its steplibs) used by the client at runtime before you perform the Service Directory Maintenance function.

The name of the library referenced for service directory maintenance is indicated in the upper right corner of the Service Directory screen (see Invoking Service Directory Maintenance). If RPCSDIR is set, the screen title contains Central, which indicates that the library displayed on the screen is not the library where you are currently logged on, but the central library specified with RPCSDIR.

Attention:

If NATCLTGS is stored in the Natural system library SYSRPC, we strongly recommend that you move NATCLTGS to the application library (or one of its steplibs) used by the client.

For further information on how to apply the Service Directory Maintenance function, refer to Specifying RPC Server Addresses described in Operating a Natural RPC Environment in the Natural RPC (Remote Procedure Call) documentation.

This section covers the following topics:


Service Directory Concept

A service directory has a hierarchical structure with a cascading list to assign subordinate to superior fields. The highest hierarchical level is node and the lowest is program. You cannot enter node, server, library and program in the same line. If you do so, an appropriate error message appears. You need to enter the value of a subordinate field in the lines below the superior field. You can assign several servers to a node, several libraries to a server and several programs to a library.

The node and server names specified in the service directory are either physical names or logical names and logical services:

Physical Nodes and Servers

Physical node and server names denote the names of real nodes (valid TCP/IP or Entire Net-Work addresses) and servers.

In Example 1 - Standard View of Service Directory, two servers are defined for one node. Both servers are connected to the same node: ETB045. The remote CALLNAT to subprogram SUB1 is executed on server NRPC001, whereas subprograms SUB2 and SUB3 are executed on server NRPC002.

The server names specified here must be identical to the server names specified for the server with the profile parameter SRVNAME described in the Parameter Reference documentation. Analogously, the node name in the service directory must be identical to the node name specified for the server with the profile parameter SRVNODE in the Parameter Reference documentation.

Location Transparency

Location transparency is a concept where physical node names can be replaced by logical node names, and a combination of physical node and server names can be replaced by logical services.

Logical node names and logical services are defined with EntireX and are assigned to physical node and server names at Natural runtime.

In Example 1 - Standard View of Service Directory, *LOCTRAN in the field Node indicates that the field Server contains the logical service NRPC001-LOGICAL. LOGBROKER=NODE in the field Node indicates the logical node name.

Related Topics:

Invoking Service Directory Maintenance

Attention:

The Service Directory Maintenance function invokes the Natural editor. As a result, data stored in the source work area may be lost when invoking Service Directory Maintenance. An appropriate message will warn you not to delete any existing entries unintentionally: choose PF12 to cancel the function or choose ENTER to confirm the action and clear the source work area.

Start of instruction set To invoke the Service Directory Maintenance function

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

    SM
  2. Choose ENTER.

    • If the service directory already contains service definitions, a window appears with the following message:

      Existing service definitions found

      In the Code field of the window, enter an A (default) to keep old definitions and append new ones and choose ENTER.

      Or:
      In the Code field of the window, enter an I to ignore all existing definitions and delete them from the service directory and choose ENTER.

    The standard view of the Service Directory screen is displayed as shown in the following example:

    Example 1 - Standard View of Service Directory

     15:32:25            *** NATURAL Remote Procedure Call ***           2004-04-14
                                  Service Directory                        SYSRPC
    
                  Node        Tr.        Server      Logon  Library     Program
     1      ETB045__________   B    ________________   _   ________    ________
     2      ________________   _    NRPC001_________   N    ________    ________
     3      ________________   _    ________________   _    SYSTEM__    ________
     4      ________________   _    ________________   _    ________    SUB1____
     5      ________________   _    NRPC002_________   Y    ________    ________
     6      ________________   _    ________________   _    SYSTEM__    ________
     7      ________________   _    ________________   _    ________    SUB2____
     8      ________________   _    ________________   _    ________    SUB3____
     9      *LOCTRAN________   _    ________________   _    ________    ________
     10     ________________   B    NRPC001-LOGICAL_   N    ________    ________
     11     ________________   _    ________________   _    SYSTEM__    ________
     12     ________________   _    ________________   _    ________    SUB1____
     13     LOGBROKER=NODE     B    ________________   N    ________    ________
     14     ________________   _    NRPC002_________   N    ________    ________
     15     ________________   _    ________________   _    SYSTEM__    ________
     16     ________________   _    ________________   _    ________    S?B*____
    
    Command ==>
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  LocTr Exit  Find  -H    +H    -P    +P    Top   Bot   <     Canc

    The Service Directory screen provides a maximum of 500 lines for input.

  3. If you choose PF11 or enter the less than (<) sign in the Command line, the extended node/server view of the Service Directory screen is displayed similar to the following example:

    Example 2 - Extended Node/Server View of Service Directory

       14:48:33            *** NATURAL Remote Procedure Call ***           2004-04-14
                                   Service Directory                        SYSRPC
    
                         Node               Tr.              Server            Logon
      1    ETB045__________________________  B  ________________________________  _
      2    ________________________________  _  NRPC001_________________________  N
      3    ________________________________  _  ________________________________  _
      4    ________________________________  _  ________________________________  _
      5    ________________________________  _  NRPC002_________________________  Y
      6    ________________________________  _  ________________________________  _
      7    ________________________________  _  ________________________________  _
      8    ________________________________  _  ________________________________  _
      9    *LOCTRAN________________________  _  ________________________________  _
      10   ________________________________  B  NRPC001-LOGICAL_________________  N
      11   ________________________________  _  ________________________________  _
      12   ________________________________  _  ________________________________  _
      13   LOGBROKER=NODE__________________  B  ________________________________  N
      14   ________________________________  _  NRPC002_________________________  N
      15   ________________________________  _  ________________________________  _
      16   ________________________________  _  ________________________________  _
    
     Command ==>
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
           Help  LocTr Exit  Find  -H    +H    -P    +P    Top   Bot   >     Canc

    If you choose PF11 or enter the greater than (>) sign in the Command line, the standard view of the Service Directory screen is displayed as shown in Example 1 - Standard View of Service Directory.

Fields on the Service Directory Screen

The Service Directory screen contains the following input fields (one entry per line):

Field Description
Node

The name of the node to which the remote CALLNAT is sent. See also Natural RPC Terminology in the Natural RPC (Remote Procedure Call) documentation.

The maximum length of input is as follows:

Standard view of the Service Directory screen: 16 characters
Extended node/server view of the Service Directory screen: 32 characters
Using the Location Transparency window (see PF2 in Direct Commands and PF Keys): 192 characters
Tr.

The transport protocol:

B indicates EntireX Broker ACI protocol.

Server

The name of the server to which the remote CALLNAT is sent. See also Natural RPC Terminology in the Natural RPC (Remote Procedure Call) documentation.

The maximum length of input is as follows:

Standard view of the Service Directory screen: 16 characters
Extended node/server view of the Service Directory screen: 32 characters
Using the Location Transparency window (see PF2 in Direct Commands and PF Keys): 192 characters
Logon

Initiates a Natural logon to the server.

 

This is possible at server or node level and applies to all definitions made at a hierarchically lower level. If the Logon option has been set for a specific server, it applies to all associated library and subprogram definitions.

 

Possible values are as follows:

   
Y If set to Y (Yes), for each non-conversational CALLNAT request or for each start of a conversation, the client initiates a Natural logon to the server using the current library name on the client, regardless of the libraries in the subordinate Library column that belongs to the Server field. You can use the Application Programming Interface USR4008N to specify a different library (see also Logging on to a Different Library in Using the Logon Option).
N
or
blank
If set to N (No) or if  no value is entered, no logon is initiated.
 

After the remote CALLNAT has been executed (successfully or not) or at the end of a conversation, the server library is reset to its previous state. For more information, see Using the Logon Option in the Natural RPC (Remote Procedure Call) documentation.

 

See also Server Command Execution.

Library SYSTEM or the name of the library to which your client application is logged on during the execution of the remote CALLNAT.
Program

The name of the remote subprogram to be accessed from the client.

 

You can enter a name or a range of names. Valid names are any combinations of one or more alphanumeric characters with one or more asterisks (*) and/or one or more question marks (?) where:

asterisk (*) denotes any string of characters,
question mark (?) denotes a single character.
 

Invalid combinations are:

   
*? An asterisk followed by a question mark is converted to ?*.
** Two or more consecutive asterisks are converted to a single asterisk.

Selection Criteria for Node and Server

At Natural runtime, the selection of a node and server depends on the value of the fields Program and Library. Comply with the following conditions:

Non-conversational CALLNAT

  1. The Library field must contain the name of the current application library or SYSTEM.

  2. The name of the subprogram specified in the CALLNAT statement must be contained in the Program field, which belongs to the Library field in point (1).

Conversational CALLNAT

  1. The Library field must contain the name of the current application library or SYSTEM.

  2. All subprograms specified in the OPEN CONVERSATION statement must be contained in a Program field, which belongs to Library field in point (1).

The node and server used for a non-conversational or conversational CALLNAT are taken from the superior Node and Server fields of the Library field in point (1).

Commands for Service Directory Maintenance

This section contains information on the commands provided on the Service Directory screen:

Line Commands

The line commands provided on the Service Directory 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.
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.

Start of instruction set To copy or move a block of lines

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

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

  3. Choose ENTER.

    The line commands disappear, the sequence numbers are displayed again and the block of lines has been marked.

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

  5. Note that you can only execute A or P on lines where at least one field is filled.

  6. Choose ENTER.

    The block of lines is copied or moved below or above the specified line.

Direct Commands and PF Keys

The following direct commands and PF keys are provided on the Service Directory screen:

Direct Command PF Key Function
EXPIRATION   The remote directory data is loaded at runtime. The expiration time in seconds determines the period of validity of this data. If directory data is requested after the expiration time set, it will automatically be reloaded. If the expiration time is set to 0, the remote directory data will not be reloaded.

With the direct command EXPIRATION, you can enter an expiration time in seconds, for example, EXPIRATION 86400. Maximum is an 8-digit number.

If you do not provide a parameter with the command, the Expiration Time window appears where you can display or modify the current time.

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

  PF1 Invokes the editor online help.
  PF2 Invokes the Location Transparency window where you can define a logical node name or a logical service as described in Defining Logical Node Names and Logical Services.
  PF3 Exit. Prompts you to save modifications and exit the Service Directory screen.
FIND PF4
Invokes the Find Item window where you can search for a name:
   
Find what Enter an alphanumeric search string of up to 32 characters.
   
Case sensitive Replace the default setting N (No) by Y (Yes) to distinguish between uppercase and lowercase characters.
   
Whole words only Replace the default setting N (No) by Y (Yes) to search for whole words only.
   

Choose ENTER to start searching and move from one hit to the next if one exists. Press PF4 to restart searching from the beginning.

The hits are marked with the cursor.

REPLACE PF16
Invokes the Replace Item window where you can search for and replace single or multiple names (not-case-sensitive):
   
Find Enter an alphanumeric search string of up to 32 characters.
   
Replace with Enter an alphanumeric replace string of up to 32 characters.
   
Whole words only Replace the default setting N (No) by Y (Yes) to search for whole words only.
   
Search only All names in the service directory are searched for matches by default (blank field entry).

You can enter one of the following letters to restrict the search to one of the following items:

     
  N Node names only
  S Server names only
  L Library names only
  P Program names only
   
Replace all Replaces all occurrences of the search string found.
 
Choose ENTER to start searching and move from one hit to the next if one exists. Press PF4 to restart searching from the beginning.

The hits are marked with the cursor.

REPLACE replace-clause   Performs the replace functions provided in the Replace Item window: see replace-clause.
-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.
  PF11 Toggles between the standard view of the Service Directory screen (see Example 1 - Standard View of Service Directory) and the extended view of the fields Node and Server (see Example 2 - Extended Node/Server View of Service Directory).
> PF11 Displays the extended view of the fields Node and Server. The extended node/server view does not display the fields Library and Program as shown in Example 2 - Extended Node/Server View of Service Directory.
< PF11 Displays the standard view of the Service Directory screen as shown in Example 1 - Standard View of Service Directory.
CANCEL PF12 Exits the Service Directory screen without saving any modifications.

replace-clause

The replace-clause of the REPLACE direct command corresponds to the replace-clause of the SYSRPC SM REPLACE system command.

../graphics/sbo3b.gif

ANY
NODE
SERVER
LIBRARY
PROGRAM

../graphics/sbc3b.gif

search-string WITH replace-string

../graphics/sbo2.gif

ALL
FIRST

../graphics/sbc2.gif

[WHOLE]

The syntax items are explained in the following table:

ANY Searches for all names specified in the service directory.

This is the default value.

NODE Searches for node names only.
SERVER Searches for server names only.
LIBRARY Searches for library names only.
PROGRAM Searches for program names only.
search-string An alphanumeric search string of up to 32 characters.
WITH Introduces the replace-string.
replace-string An alphanumeric replace string of up to 32 characters.
ALL Replaces all occurrences of the search string found.
FIRST Replaces only the first occurrence of the search string found.

This is the default value.

WHOLE Replaces only occurrences that match the whole search string.

Note:
The search operation is not case-sensitive.

Defining Logical Node Names and Logical Services

Logical node names or logical services can only be defined for node or server fields that already contain any values.

Note that defining a logical service, the original (physical) node name will be replaced by *LOCTRAN and it is not possible to automatically convert back logical node names or logical services. For instructions on removing logical names and servers, see To remove a logical node name or logical service.

Start of instruction set To define a logical service

  1. Place the cursor on a Server field and choose PF2 (LocTr).

    The Location Transparency - Logical Service window appears.

  2. If desired, modify the existing values and choose ENTER.

    The Server Type Conversion window appears as an additional window. Choose either of the following options:

    • Enter a Y (Yes) and choose ENTER to confirm and execute the conversion.

      The value in the field Node that relates to the specified server is replaced by the following character string: *LOCTRAN. This string indicates that a node/server combination was converted to a logical service.

    • Enter any character except Y or do not enter any value to cancel the conversion.

      The physical node and server names are retained.

Start of instruction set To define a logical node name

  1. Place the cursor on a Node field and choose PF2 (LocTr).

    The Location Transparency - Logical Node Name window appears with the preset value of LOGBROKER=name where name denotes the logical EntireX Broker name.

    If desired, modify name but do not modify the character string LOGBROKER=.

  2. Choose ENTER to confirm and execute the conversion.

    The physical node name is converted to a logical name.

    Or:
    Choose PF12 (Canc) to cancel the conversion.

    The physical node name is retained.

Start of instruction set To remove a logical node name or logical service

  • For a logical node name:
    In the Node field, remove the character string LOGBROKER=.

    For a logical service:
    Delete the logical service and insert physical server(s) by using the line commands D and I as described in Line Commands.