4 Creating and setting up client-side programs

4.1 Creating a Ninf-G Client

4.2 Setting up the Ninf-G Client operating environment

4.3 Ninf-G Client configuration file specifications

4.3.1 Structure of the configuration file

The Ninf-G Client configuration file is a text file which contains settings information that is required for the operation of Ninf-G Client. It consists of seven sections, which are INCLUDE, CLIENT, LOCAL_LDIF, FUNCTION_INFO, MDS_SERVER, SERVER, and SERVER_DEFAULT.

Examples of section and attribute descriptions are shown below.

#comment
<section>
attribute    value    # comment

attribute    value    # comment
attribute    value    # comment
</section>
...

Examples of errors in description are shown below.

<section>Attribute Value
                             # Section and attribute on the same line
 
AttributeValue     # No delimiter between the attribute and attribute value
 
Attribute  Value   Attribute  Value
                             # Multiple attributes on the same line
 
Attribute                    # Attribute and attribute value
Value                        # extend across more than one line.
 
Attribute \
Value                        # Line continued with a backslash (\)
 
Attribute                    #  No attribute value
</section>
 
<CLIENT>                     # Multiple definitions in a section where
...                          #
</CLIENT>                    #
<CLIENT>                     # multiple definitions are not allowed
...                          #
</CLIENT>                    #
 
<MDS_SERVER>                 # Attribute value redundancy within a section
hostname  example.org        #  where multiple definitions are allowed
</MDS_SERVER>
<MDS_SERVER>
hostname  example.org        #
</MDS_SERVER>                #
 
<LOCAL_LDIF>                 # Attribute value redundancy
filename  example.ngdef      # for an attribute that allows
filename  example.ngdef      #  multiple attribute values
</LOCAL_LDIF>
 
<SERVER>
HostName  example.com        # Upper and lower case letters
hostname  EXAMPLE.COM        # Upper and lower case letters
</SERVER>

4.3.2 Specifying the unit for time

When a time value is specified as an attribute value (for time-out or other such attributes), a unit of time can be specified (e.g., 30 s, 30 sec or 30 seconds).

It is also possible to specify 'minute' or 'hour' as the time unit. Character strings such as 'se' and 'seco' are also interpreted to mean second, but strings that are not contained in 'second', such as 'set' will cause an error.

4.3.3 Specifying the unit for number of bytes

When specifying the number of bytes as an attribute value for attributes such as log file size, units (*) such as 1 K or 1 Kilo can be specified. Mega and Giga can also be specified as a unit for number of bytes.

Character strings such as Me, Meg, etc. are also interpreted to mean Mega, but strings that are not contained in Mega, such as Ma cause an error.

(*) 1 K = 1024 bytes, 1 M = 1024 Kbytes, 1 G = 1024 Mbytes

Each section of the configuration file is described below.

4.3.4 INCLUDE section

The INCLUDE section allows multiple definitions.

An example of an INCLUDE section description is shown below.

<INCLUDE>
filename    file name
filename    file name
</INCLUDE>

The attributes and attribute values of the INCLUDE section are shown below.

Attribute Attribute value Default value Multiple Explanation
filename File name None Yes File to include

4.3.5 CLIENT section

The CLIENT section does not allow multiple definitions.

An example of a CLIENT section description is shown below.

<CLIENT>
hostname                  Host name
save_sessionInfo          Session information count
loglevel                  [0-5]
loglevel_globusToolkit    [0-5]
loglevel_ninfgProtocol    [0-5]
loglevel_ninfgInternal    [0-5]
loglevel_ninfgGrpc        [0-5]
log_filePath              File name
log_suffix                Suffix
log_nFiles                Number of files
log_maxFileSize           Number of bytes
log_overwriteDirectory    [true/false]
refresh_credential        Seconds
</CLIENT>

The attributes and attribute values of the CLIENT section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name globus_libc_ gethostname() No The host name of the client
save_sessionInfo Session information count 256 No The number of session information units to be saved
loglevel [0-5] 2 No Overall log level
loglevel_globusToolkit [0-5] 2 No Globus Toolkit API error log level
loglevel_ninfgProtocol [0-5] 2 No Ninf-G protocol error log level
loglevel_ninfgInternal [0-5] 2 No Ninf-G internal error log level
loglevel_ninfgGrpc [0-5] 2 No Grid RPC API error log level
log_filePath File name stderr No The log file name
log_suffix Suffix Sequence number No The log file suffix
log_nFiles Number of files 1 No The number of files for log
log_maxFileSize Number of bytes 1M/unlimited No Maximum number of bytes for log file
log_overwriteDirectory [true/false] false No Over-write permission for log directory
refresh_credential Seconds 0 No Refreshing proxy credential interval

The log level can be specified by using the strings listed in the 'Meaning' column in the table below as well as by using a number value.

The meanings of the log level values are described below.

Value Meaning Explanation
0 Off Nothing is output.
1 Fatal A fatal error is output.
2 Error A nonfatal error is output.
3 Warning A warning error is output.
4 Information Guidance or other such information is output.
5 Debug Debugging information is output.

4.3.6 LOCAL_LDIF section

The LOCAL_LDIF section allows multiple definitions. The LOCAL_LDIF section may be omitted.

An example of a LOCAL_LDIF section description is shown below.

<LOCAL_LDIF>
filename    file name
filename    file name
</LOCAL_LDIF>

The attributes and attribute values of the LOCAL_LDIF section are shown below.

Attribute Attribute value Default value Multiple Explanation
filename File name None Yes Local LDIF file

4.3.7 FUNCTION_INFO section

The FUNCTION_INFO section allows multiple definitions. The FUNCTION_INFO section may be omitted.

An example of a FUNCTION_INFO section description is shown below.

<FUNCTION_INFO>
hostname     Host name
funcname     Function name

path         Path
staging      [true/false]
backend      Backend
session_timeout Seconds
</FUNCTION_INFO>

The attributes and attribute values of the FUNCTION_INFO section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name None No Server machine host name
funcname Function name None No The function name of the remote function
path Path None No The path to the Ninf-G Executable
staging [true/false] false No Staging enabled or disabled
backend Backend normal No Backend software by which Ninf-G Executable is launched
session_timeout Seconds 0 No RPC execution timeout

4.3.8 MDS_SERVER section

The MDS_SERVER section allows multiple definitions. The MDS_SERVER section can be omitted.

When an MDS request for information is made, the request is issued to the MDS server specified by the MDS_SERVER section defined in the configuration file. The search is executed repeatedly in order, beginning with the first definition, until the information has been found or the last MDS_SERVER defined in the section has been searched.

An example of MDS_SERVER section description is shown below.

<MDS_SERVER>
hostname          Host name
port              Port number
vo_name           VONAME
client_timeout    Seconds
server_timeout    Seconds
</MDS_SERVER>

The attributes and attribute values of the MDS_SERVER section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name None No MDS server host name
port Port number 2135 No MDS server port number
vo_name VONAME Local No GIIS vo name
client_timeout Seconds 0 No The client time-out time
server_timeout Seconds 0 No The server time-out time

4.3.9 SERVER section

The SERVER section allows multiple definitions.

When the SERVER section contains multiple definitions, the following API checks to see if remote function information is registered in the first-defined SERVER. If it is, that server is used. If it is not, a check is made for registered remote function information in the second SERVER. This is repeated until remote function information is found.

An example of a SERVER section description is shown below.

<SERVER>
hostname                      Host name
hostname                      Host name  host name  host name

port                          Port number
mds_hostname                  host name
mpi_runNoOfCPUs               [function name]=number of CPUs
gass_scheme                   [http/https]
crypt                         [false/SSL/GSI]
protocol                      [XML/binary]
force_xdr                     [true/false]
jobmanager                    JOBMANAGER
subject                       "Subject"

job_startTimeout              Seconds
job_stopTimeout               Seconds
job_maxTime                   Minutes
job_maxWallTime               Minutes
job_maxCpuTime                Minutes
job_queue                     queue name
job_project                   project name
job_hostCount                 Number of nodes
job_minMemory                 Size
job_maxMemory                 Size

heartbeat                     Seconds
heartbeat_timeoutCount        Times
redirect_outerr               [true/false]
tcp_nodelay                   [true/false]
tcp_connect_retryCount        Counts
tcp_connect_retryBaseInterval Seconds
tcp_connect_retryIncreaseRatio Ratio
tcp_connect_retryRandom       [true/false]
argument_transfer             [wait/nowait/copy]
compress                      [raw/zlib]
compress_threshold            Number of bytes
argument_blockSize            Number of bytes
workDirectory                 Directory name
coreDumpSize                  Size

commLog_enable                [true/false]
commLog_filePath              File name
commLog_suffix                Suffix
commLog_nFiles                Number of files
commLog_maxFileSize           Number of bytes
commLog_overwriteDirectory    [true/false]

debug                         [true/false]
debug_display                 DISPLAY
debug_terminal                Command path name
debug_debugger                Command path name
debug_busyLoop                [true/false]

environment                   Variable name
environment                   Variable name = value
</SERVER>

The attributes and attribute values of the SERVER section are shown below.

Attribute Attribute value Default value Multiple Explanation
hostname Host name None Yes Server machine host name
port Port number 2119 No The server port number on which the Globus gatekeeper is listening
mds_hostname Host name None No MDS server host name
mpi_runNoOfCPUs Function name, Number of CPUs None Yes The number of CPUs used by MPI function
gass_scheme [http/https] http No GASS server scheme
crypt [false/SSL/GSI] false No Specification of the communication path encryption
protocol [XML/binary] XML No Specifies the protocol.
force_xdr [true/false] false No Makes XDR compulsory.
jobmanager JOBMANAGER None No The job manager used on the server machine
subject Subject None No Subject of resource manager contact
job_startTimeout Seconds 0 No The time-out at job startup
job_stopTimeout Seconds -1 No The time-out for when the job stops
job_maxTime Minutes None No The maximum job execution time
job_maxWallTime Minutes None No The maximum job execution wall clock time
job_maxCpuTime Minutes None No The maximum job execution cpu time
job_queue queue name None No A remote queue name
job_project project name None No A remote project name
job_hostCount Number of nodes None No Number of nodes (for SMP clusters)
job_minMemory Size None No Minimum amount of memory, in Megabytes
job_maxMemory Size None No Maximum amount of memory, in Megabytes
heartbeat Seconds 60 No The heart-beat interval
heartbeat_timeoutCount Times 5 No The heart-beat time-out times
redirect_outerr [true/false] true No Ninf-G Executable output redirect
tcp_nodelay [true/false] false No TCP_NODELAY socket option
tcp_connect_retryCount Counts 4 No The maximum number of retries for a TCP connection
tcp_connect_retryBaseInterval Seconds 1 No The base interval time for the first retry
tcp_connect_retryIncreaseRatio Ratio 2.0 No The increase ratio for calculating the maximum interval time between retries
tcp_connect_retryRandom [true/false] true No A flag that specifies whether the random value is used or not for the interval time
argument_transfer [wait/nowait/copy] wait No Returns the called function for an asynchronous function call Timing (Wait or do not wait for completion of argument transfer.)
compress [raw/zlib] raw No Compression method
compress_threshold Number of bytes 64KBytes No Threshold for performing compression
argument_blockSize Number of bytes 16KBytes No The block size of transferred arguments
workDirectory Directory name The path to the Ninf-G Executable No The working directory for Ninf-G Executable
coreDumpSize Size Undefined No Core dump size for Ninf-G Executable
commLog_enable [true/false] false No Whether the communication log output is enabled or disabled
commLog_filePath File name stderr No Communication log file name
commLog_suffix Suffix Sequence number No The communication log file suffix
commLog_nFiles Number of files 1 No The number of files for communication log output
commLog_maxFileSize Number of bytes 1M/unlimited No Maximum number of bytes for the communication log file
commLog_overwriteDirectory [true/false] false No Overwrite permission for the communication log directory
debug [true/false] false No Whether the debugging function is enabled or not
debug_display DISPLAY Environment variable No Debugging display
debug_terminal Command path name Environment variable No Path to the debugging terminal emulator
debug_debugger Command path name Environment variable No Debugger path
debug_busyLoop [true/false] false No Wait attach from debugger or not
environment Character string None Yes Environment variable
Note: mpi_runCommand attribute is obsoleted in 2004/06/30. Changed implementation to use Globus RSL (jobType=mpi), to invoke MPI function handle.

4.3.10 SERVER_DEFAULT section

The SERVER_DEFAULT section does not allow multiple definitions. This section may be omitted.

The SERVER_DEFAULT section defines the default values for attributes which are used when attributes are omitted in the SERVER section.

The description of the SERVER_DEFAULT section is the same as the SERVER section, except that the attribute "hostname" is not described.

The SERVER_DEFAULT section may also be described in the configuration file or other such place. (*)

(*) For example, even if the SERVER_DEFAULT section is written later than the SERVER section, if attributes are omitted in the previously described SERVER section, the attributes defined in the SERVER_DEFAULT section are used.

4.4 Running the Ninf-G Client program

4.5 Creating application programs

Ninf-G supports the GridRPC API for C and Java.

In this section, the flow of an application program (written in C) for using GridRPC is described and a few typical GridRPC API functions are introduced.

Of the functions described here, those that contain *_np are not included in the GridRPC API standard (i.e., they are specific to Ninf-G).

A full list of the GridRPC APIs and detailed explanation of each API can be found in chapter 7, "API Reference".

The functions used in the above processes are described below.

  1. Initialization

    The following function is used for initialization.

    grpc_error_t grpc_initialize(char *configFile)

    This function accepts the name of the configuration file as an argument, reads the file named by the argument, analyzes the content, and saves the values.

    If the argument value is NULL, the file specified by the NG_CONFIG_FILE environment variable is taken to be the configuration file.

    As the return value, an error status code is returned to inform of failure to read the configuration file or failure to save the values that were read.

    An example of using grpc_initialize() is given below. (In this example, the configuration file name is taken from the command line argument and that value is used as the argument.)

    
main (int argc, char *argv[]) {
       grpc_error_t result;
       char *configFile = argv[1];

       result = grpc_initialize(configFile);
       ...

  2. Creation of handles

    In GridRPC, "handles" are used when performing operations such as executing remote functions and remote methods. A handle must be created before executing a remote function or remote method, but the type of handle to create differs with the type of Ninf-G Executable used.

    If only one remote function is defined for the Ninf-G Executable used, a "function handle" is used; if multiple remote methods are defined, an "object handle" is used.

    Functions for creating both kinds of handles are shown below.

    These functions accept a 'server name' and 'function or class name', and creates a handle for operating the specified Ninf-G Executable on the specified server.

    As the return value, an error code is returned to inform of failure to create the handle.

    For example, a function handle is created as follows.

    
    grpc_function_handle_t *handle;
    grpc_function_handle_init(&handle, "server.example.org", "lib/mmul");

    The following functions for creating multiple handles at one time are also provided by Ninf-G. (See Section 7 for details)

  3. Calling and synchronizing remote functions and remote methods

    The handle just created can be used to call the specified remote function or remote method on the server. When the call is made, the value of the argument defined by the Ninf-G IDL must be passed.

    The functions for calling a function differ for a function handle and an object handle. When calling a remote method with an object handle, the name of the remote method must be specified.

    Remote functions and remote methods can be called in two ways, with a 'synchronous call' and with an 'asynchronous call'.

    The synchronous call does not return until the execution of the remote function or remote method is completed.

    The asynchronous call returns either at the beginning or at the completion of sending the arguments to the remote function or remote method; it then waits for the completion of the remote function or remote method to obtain the result. (The return timing of the function that makes the asynchronous call can be specified in the configuration file.)

  4. Destruct handles

    For releasing resources, the unnecessary "handles" must be destructed. The function for destructing differs with the type of "handles".

    Functions for destructing handles are shown below.

    These functions destruct the specified handle.

    As the return value, an error status code is returned to inform of failure to destruct the handle.

    If two or more handles were created at once, then the following functions for destructing multiple handles at one time must be used.

  5. Termination processing

    The following function is used to perform the termination processing.

    grpc_error_t grpc_finalize()

    This function executes the processing for when Ninf-G is terminated.

    The return value is an error status code to inform when the termination processing fails.

last update : $Date: 2005/08/04 09:32:49 $