Network Resource String Syntax

Overview

One common application of NRS strings is the specification of login parameters for a remote process (RPC) GemStone application. An RPC login typically requires you to specify a GemStone repository monitor and a Gem service on a remote server, using NRS strings that include the remote server’s hostname. For example, to log in from Topaz to a Stone process called “gs64stone” running on node “handel”, you would specify two NRS strings:

topaz> set gemstone !@handel!gs64stone

topaz> set gemnetid !@handel!gemnetobject

Many GemStone processes use network resource strings, so the strings show up in places where command arguments are recorded, such as the GemStone log file. Looking at log messages will show you the way an NRS works. For example:

Opening transaction log file for read,

filename = !@oboe#dbf!/user1/gemstone/data/tranlog0.dbf

An NRS can contain spaces and special characters. On heterogeneous network systems, you need to keep in mind that the various UNIX shells have their own rules for interpreting these characters. If you have a problem getting a command to work with an NRS as part of the command line, check the syntax of the NRS recorded in the log file. It may be that the shell didn’t expand the string as you expected.

NOTE
Before you begin using network resource strings, make sure you understand the behavior of the software that will process the command.

See each operating system’s documentation for a full discussion of its own rules about escaping certain characters in NRS strings that are entered at a command prompt.

If there is a space in the NRS, you can replace the space with a colon (:), or you can enclose the string in quotes (" "). For example, the following network resource strings are equivalent:

% waitstone !@oboe#auth:user@password!gs64stone

% waitstone "!@oboe#auth user@password!gs64stone"

Defaults

The following items uniquely identify a network resource:

• Communications protocol— such as TCP/IP
• Destination node—the host that has the resource
• Authentication of the user—such as a system authorization code
• Resource type—such as server, database extent, or task
• Environment—such as a NetLDI, a directory, or the name of a log file
• Resource name—the name of the specific resource being requested.

A network resource string can include some or all of this information. In most cases, you need not fill in all of the fields in a network resource string. The information required depends upon the nature of the utility being executed and the task to be accomplished. Most GemStone utilities provide some context-sensitive defaults. For example, the Topaz interface prefixes the name of a Stone process with the #server resource identifier.

When a utility needs a value for which it does not have a built-in default, it relies on the system-wide defaults described in the syntax productions in Syntax. You can supply your own default values for NRS modifiers by defining an environment variable named GEMSTONE_NRS_ALL in the form of the nrs-header production. If GEMSTONE_NRS_ALL defines a value for the desired field, that value is used in place of the system default. (There can be no meaningful default value for “resource name.”)

A GemStone utility picks up the value of GEMSTONE_NRS_ALL as it is defined when the utility is started. Subsequent changes to the environment variable are not reflected in the behavior of an already-running utility.

When a client utility submits a request to a NetLDI, the utility uses its own defaults and those gleaned from its environment to build the NRS. After the NRS is submitted to it, the NetLDI then applies additional defaults if needed. Values submitted by the client utility take precedence over those provided by the NetLDI.

Notation

Terminal symbols are printed in boldface. They appear in a network resource string as written:

#server

Nonterminal symbols are printed in italics. They are defined in terms of terminal symbols and other nonterminal symbols:

username ::= nrs-identifier

Items enclosed in square brackets are optional. When they appear, they can appear only one time:

address-modifier ::= [protocol] [@ node]

Items enclosed in curly braces are also optional. When they appear, they can appear more than once:

nrs-header ::= ! [address-modifier] {keyword-modifier} !

Parentheses and vertical bars denote multiple options. Any single item on the list can be chosen:

protocol ::= ( tcp | serial | default )

Syntax

nrs ::= [nrs-header] nrs-body

where:

nrs-header ::= ! [address-modifier] {keyword-modifier} [resource-modifier]!
All modifiers are optional, and defaults apply if a modifier is omitted. The value of an environment variable can be placed in an NRS by preceding the name of the variable with “$”. If the name needs to be followed by alphanumeric text, then it can be bracketed by “{” and “}”. If an environment variable named foo exists, then either of the following will cause it to be expanded: $foo or ${foo}. Environment variables are only expanded in the nrs-header. The nrs-body is never parsed.

address-modifier ::= [protocol] [@ node]
Specifies where the network resource is.

protocol ::= ( tcp | serial | default )
Supports heterogeneous connections by predicating address on a network type. If no protocol is specified, GCI_NET_DEFAULT_PROTOCOL is used. On UNIX hosts, this default is tcp.

node ::= nrs-identifier
If no node is specified, the current machine’s network node name is used. The identifier may also be an Internet-style numeric address. For example:

!@120.0.0.4#server!cornerstone

nrs-identifier ::= identifier
Identifiers are runs of characters; the special characters !, #, $, @, ^ and white space (blank, tab, newline) must be preceded by a “^”. Identifiers are words in the UNIX sense.

keyword-modifier ::= ( authorization-modifier | environment-modifier)
Keyword modifiers may be given in any order. If a keyword modifier is specified more than once, the latter replaces the former. If a keyword modifier takes an argument, then the keyword may be separated from the argument by a space or a colon.

authorization-modifier ::= ( (#auth | #encrypted) [:] username [@ password] )
#auth specifies a valid OS user name on the target network. A valid OS user password is needed only if the resource type requires authentication. #encrypted is used by GemStone utilities. This type of authorization is the default.

username ::= nrs-identifier

If no OS user name is specified, the default is the current OS user. See the earlier discussion of authorization-modifier.

password ::= nrs-identifier
Only needed if the resource type requires authentication; see the earlier discussion of authorization-modifier.

environment-modifier ::= ( #netldi | #dir | #log ) [:] nrs-identifier
#netldi causes the named NetLDI to be used to service the request. If no NetLDI is specified, the default is gs64ldi. When you specify the #netldi option, the nrs-identifier is either the name of a NetLDI service or the port number at which a NetLDI is running.

#dir sets the default directory of the network resource. It has no effect if the resource already exists. If a directory is not set, the pattern “%H” (home directory) is used. (See the definition of nrs-identifier.

#log sets the name of the log file of the network resource. It has no effect if the resource already exists. If the log name is a relative path, it is relative to the working directory. If a log name is not set, the pattern “%N%P%M.log” is used, as described below, and following the syntax in the definition of nrs-identifier

The argument to #dir or #log can contain patterns that are expanded in the context of the created resource. The following patterns are supported:
%H home directory
%M machine’s network node name
%N executable’s base name
%P process pid
%U user name
%% %

resource-modifier ::= ( #server | #spawn | #task | #dbf | #monitor | #file )
Identifies the intended purpose of the string in the nrs-body. An NRS can contain only one resource modifier. The default resource modifier is context sensitive. For instance, if the system expects an NRS for a database file, then the default is #dbf.

#server directs the NetLDI to search for the network address of a server, such as a Stone or another NetLDI. If successful, it returns the address. The nrs-body is a network server name. A successful lookup means only that the service has been defined; it does not indicate whether the service is currently running. A new process will not be started. (Authorization is needed only if the NetLDI is on a remote node and is running in secure mode.)

#task starts a new Gem. The nrs-body is a NetLDI service name (such as “gemnetobject”), followed by arguments to the command line. The NetLDI creates the named service by looking first for an entry in $GEMSTONE/sys/services.dat, and then in the user’s home directory for an executable having that name. The NetLDI returns the network address of the service. (Authorization is needed to create a new process unless the NetLDI is in guest mode.) The #task resource modifier is also used internally to create page servers.

#dbf is used to access a database file. The nrs-body is the file spec of a GemStone database file. The NetLDI creates a page server on the given node to access the database and returns the network address of the page server. (Authorization is needed unless the NetLDI is in guest mode).

#spawn is used internally to start the garbage collection and other service Gem processes.

#monitor is used internally to start up a shared page cache monitor.

#file means the nrs-body is the file spec of a file on the given host (not currently implemented).

nrs-body ::= unformatted text, to end of string
The nrs-body is interpreted according to the context established by the resource-modifier. No extended identifier expansion is done in the nrs-body, and no special escapes are needed.