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

• Invoking Service Directory Maintenance

• Fields on the Service Directory Screen

• Commands for Service Directory Maintenance

• Defining Logical Node Names and Logical Services

---

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

• Location Transparency

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:

• Defining Logical Node Names and Logical Services.

• Using Location Transparency in the section Operating a Natural RPC Environment in the Natural RPC (Remote Procedure Call) documentation.

• The relevant sections in the EntireX documentation.

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.

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

• Direct Commands and PF Keys

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.

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.

ANY NODE SERVER LIBRARY PROGRAM

search-string WITH replace-string

ALL FIRST

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

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.

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.

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.