Service Directory Maintenance

#### Search Results

Search

# 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

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:00:11            ***** NATURAL SYSRPC UTILITY *****              2016-07-18
                                   - Service Directory -             Library 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.

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

        15:09:01            ***** NATURAL SYSRPC UTILITY *****              2016-07-18
                                   - Service Directory -             Library 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 Local 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, the logon is not 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

- Local 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 local 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. The cursor is placed in the first new line below the column Server or Library depending on the item (node, server, library, program) contained in the line where you enter the command. Examples: If the line contains a node or server name, the cursor is placed below the Server column. If the line contains a library or program name, the cursor is placed below the Library column.
`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.

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

5. Choose ENTER.

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

### Local Commands and PF Keys

The following local commands can be entered in the Command line of the Service Directory screen and/or are provided as PF keys:

Local 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 local 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. It corresponds to the replace-clause of the `SYSRPC SM REPLACE` command.
`-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.

### On this page

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