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 NTRPC/RPC keyword subparameter 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.

API for Service Directory Maintenance Functions:

You can use the application programming interface (API) USR8216N to perform service directory maintenance functions. USR8216N retrieves an existing service directory and adds, changes or deletes entries in the service directory. USR8216N is supplied in the Natural SYSEXT system library. For handling instructions, see Using a Natural API in the section SYSEXT Utility.

This section covers the following topics:

Service Directory Concept
Invoking Service Directory Maintenance
Fields on the Service Directory Screen
Commands for Service Directory Maintenance

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.

Nodes and Servers

Nodes 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 NTRPC/RPC keyword subparameter 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 NTRPC/RPC keyword subparameter SRVNODE described in the Parameter Reference 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

In the Code field of the Client Maintenance menu, enter the following command:
```
SM
```

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 ***           2016-01-27
                              Service Directory                        SAGTST

              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      ________________   _    ________________   _    ________    ________ 
 10     ________________   _    ________________   _    ________    ________ 
 11     ________________   _    ________________   _    ________    ________ 
 12     ________________   _    ________________   _    ________    ________ 
 13     ________________   _    ________________   _    ________    ________ 
 14     ________________   _    ________________   _    ________    ________ 
 15     ________________   _    ________________   _    ________    ________ 
 16     ________________   _    ________________   _    ________    ________ 

Command ==>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Long  Exit  Find  -H    +H    -P    +P    Top   Bot   <     Canc

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

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 ***           2016-01-27
                               Service Directory                        SAGTST

                     Node               Tr.              Server            Logon
  1    ETB045__________________________  B  ________________________________  _
  2    ________________________________  _  NRPC001_________________________  N
  3    ________________________________  _  ________________________________  _
  4    ________________________________  _  ________________________________  _
  5    ________________________________  _  NRPC002_________________________  Y
  6    ________________________________  _  ________________________________  _
  7    ________________________________  _  ________________________________  _
  8    ________________________________  _  ________________________________  _
  9    ________________________________  _  ________________________________  _
  10   ________________________________  _  ________________________________  _
  11   ________________________________  _  ________________________________  _
  12   ________________________________  _  ________________________________  _
  13   ________________________________  _  ________________________________  _
  14   ________________________________  _  ________________________________  _
  15   ________________________________  _  ________________________________  _
  16   ________________________________  _  ________________________________  _

 Command ==>
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Long  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
Long Name window (see PF2 in Direct Commands and PF Keys) of the Service Directory screen:	up to 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

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`

The Library field must contain the name of the current application library or SYSTEM.
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`

The Library field must contain the name of the current application library or SYSTEM.
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

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.

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 Opens the Long Name window where you can enter a node name of up to 192 characters.

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.