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 a Ninf-G Client. It consists of seven sections, which are INCLUDE, CLIENT, LOCAL_LDIF, FUNCTION_INFO, MDS_SERVER, INVOKE_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 be included

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]
tmp_dir                   Directory
refresh_credential        Seconds
invoke_server_log         log name
fortran_compatible        [true/false]
handling_signals          Signals ...
listen_port               Port number 
listen_port_authonly      Port number 
listen_port_GSI           Port number 
listen_port_SSL           Port number 
tcp_nodelay               [true/false]
</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
tmp_dir For temporary files /tmp No The directory in which temporary files are placed
refresh_credential Seconds 0 No Refreshing proxy credential interval
invoke_server_log log name None No Invoke Server log filename
fortran_compatible [true/false] false No Fortran compatible mode
handling_signals Signal names/numbers SIGHUP SIGINT SIGTERM No Handling signals
listen_port Port number 0 No The port number for listening requests for unencrypted connections
listen_port_authonly Port number 0 No The port number for listening requests for connections by authentication only
listen_port_GSI Port number 0 No The port number for listening requests for connections encrypted by GSI
listen_port_SSL Port number 0 No The port number for listening requests for connections encrypted by SSL.
tcp_nodelay [true/false] false No TCP_NODELAY socket option

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 filename

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 for information.

An example of MDS_SERVER section description is shown below.

<MDS_SERVER>
hostname          Host name
tag               Tag name
type              Type
port              Port number
protocol          protocol name
path              service path
subject           "Subject"
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
tag Tag name None No MDS Server tag name
type Type MDS2 No MDS type
port Port number 2135 No MDS server port number
protocol protocol name https No MDS protocol
path service path default service path No MDS path
subject Subject None No MDS subject
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 INVOKE_SERVER section

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

Note: This section appeared in Ninf-G Version 4.0.0.

Note: The Invoke Server feature is supported only for pthreads flavors.

An example of an INVOKE_SERVER section description is shown below.

<INVOKE_SERVER>
type           type name
path           path name
max_jobs       Number of jobs
log_filePath   path of logfile
status_polling Seconds
option         "option string"
</INVOKE_SERVER>

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

Attribute Attribute value Default value Multiple Explanation
type type name None No Invoke Server type
path path name $NG_DIR/bin/
ng_invoke_server.[type] 		No Invoke Server executable file path
max_jobs Number of jobs 0 No max jobs for one Invoke Server
log_filePath path None No log file path
status_polling Seconds 0 No Polling interval
option "option string" None Yes option

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

tag                           Tag name
port                          Port number
mds_hostname                  Host name
mds_tag                       Tag name
invoke_server                 Type
invoke_server_option          "option string"
mpi_runNoOfCPUs               [function name=]number of CPUs
gass_scheme                   [http/https]
crypt                         [false/authonly/SSL/GSI]
protocol                      [XML/binary]
force_xdr                     [true/false]
jobmanager                    JOBMANAGER
subject                       "Subject"
client_hostname               Host name

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
job_rslExtensions             "extension string"

heartbeat                     Seconds
heartbeat_timeoutCount        Times
heartbeat_timeoutCountOnTransfer Times
redirect_outerr               [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
tag Tag name None No Server tag 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
mds_tag Tag name None No MDS tag name
invoke_server type None No Invoke Server type
invoke_server_option option string None Yes Invoke Server option
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/authonly/SSL/GSI] false No Method of authentication and encryption for communication paths
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
client_hostname Host name hostname of CLIENT section No Client machine host name
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
job_rslExtensions extension string None No RSL extensions
heartbeat Seconds 60 No The heart-beat interval
heartbeat_timeoutCount Times 5 No The heart-beat time-out times
heartbeat_timeoutCountOnTransfer Times 5 No The heart-beat time-out times on transfer
redirect_outerr [true/false] true No Ninf-G Executable output redirect
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 for attach from debugger or not
environment Character string None Yes Environment variable

4.3.11 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 places. (*)

(*) 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 Invoke Server setup

Ninf-G4 implements mechanisms for remote process invocation as a separate module called Ninf-G Invoke Server. This architecture enables to support any job submission interfaces by implementing Ninf-G Invoke Server for the interface.

Users must specify the Invoke Server for each server in Ninf-G Client Configuration file except for Pre-WS GRAM. RPC mechanisms for Pre-WS GRAM is embedded in Ninf-G Library and it is not necessary to use Invoke Server for Pre-WS GRAM.

Here is an example of the description of <SERVER> section in the Ninf-G Client Configuration file for specifying WS GRAM as a job submission interface.


<SERVER>
hostname your-host
invoke_server GT4py
</SERVER>

Invoke Server can be set and configured in the Ninf-G Client Configuration file as described above. The details of the configuration of Invoke Server are described in sections 4.3.9 and 4.3.10.

Each Invoke Server may have its own options. In order to specify such options, the following attributes are provided in the Ninf-G Client Configuration file.

Example: 

<SERVER>
hostname your-host
invoke_server GT4py
invoke_server_option "delegate_full_proxy true"
</SERVER>

Some attributes in <SERVER> section are interpreted by each Invoke Server. For example, Invoke Server GT4py interprets "port" attribute as the port number of WS GRAM and Invoke Server SSH interprets "port" attribute as the port number of sshd.

Note: The Invoke Server feature is supported only for pthreads flavors.

4.4.1 Invoke Server GT4py

Invoke Server GT4py invokes Ninf-G Executable via WS GRAM.

  1. Prerequisite

    GT4 must be installed on both client and server. globusrun-ws command must be available on the client and remote server must be able to accept WS GRAM access.

  2. Install

    Invoke Server GT4py is automatically installed through the Ninf-G installation processes described in section 2 of this manual.

  3. Extra options

    Invoke Server GT4py accepts the following extra options.

  4. RSL extensions

    WS GRAM RSL has <extensions> tag, which enables the user to pass extra information to WS GRAM server.

    Invoke Server handles this feature by using job_rslExtensions attribute in <SERVER> section.

  5. Using staging function

    Executable staging on WS GRAM server via Invoke Server GT4py requires the following steps in advance.

    1. Invoke GridFTP servers on both server and client hosts.

      Invoke Server GT4py requires GridFTP servers on both remote and local hosts. The GridFTP server should be invoked either directly or via inetd/xinetd daemon. The port for the GridFTP server is not limited to the default port 2811.

    2. Specify the port number for client-side GridFTP server in the client configuration file.

      If the client-side GridFTP server does not use the default port (2811), the port number of the GridFTP server must be specified in client configuration file. The port number can be specified by gsiftp_port option in invoke_server_option attribute in <SERVER> section.

      
example:
<SERVER>
invoke_server GT4py
invoke_server_option "gsiftp_port 12811"
...
</SERVER>

    3. Specify subject name for authentication.

      Subject names which are used for mutual authentication between WS GRAM container and client-side GridFTP server depends on the owner of those daemons.

      If they are invoked by the system, subject name of the host certificate is used. If they are invoked by a user, subject name of the user certificate is used.

      According to the combination of the owners of the WS GRAM container and the client-side GridFTP server, some attributes need to be specified in the client configuration file.

      • Case 1: Both the WS GRAM container and the client-side GridFTP server are run by the system.

        It is not necessary to specify the subject name.

      • Case 2: The WS GRAM container is run by the system and the client-side GridFTP server is run by a user.

        The subject name of the user must be specified by staging_source_subject attribute in <SERVER> section.

        
<SERVER>
invoke_server_option "staging_source_subject /Subject/of/User"
...
</SERVER>

      • Case 3: Both the WS GRAM container and the client-side GridFTP server are run by a user.

        The subject name of the user must be specified by subject attribute in <SERVER> section.

        
<SERVER>
subject "/Subject/of/User"
...
</SERVER>

      • Case 4: The WS GRAM container is run by a user and the client-side GridFTP server is run by the system.

        The subject name of the user must be specified by subject attribute in <SERVER> section. The subject name of the client-side host must be specified by staging_source_subject attribute in <SERVER> section. The subject name of the user must be specified by staging_destination_subject and deletion_subject attributes in <SERVER> section.

        
<SERVER>
subject "/Subject/of/User"
invoke_server_option "staging_source_subject /Subject/of/ClientHost"
invoke_server_option "staging_destination_subject /Subject/of/User"
invoke_server_option "deletion_subject /Subject/of/User"
...
</SERVER>

    4. Create a scratch directory for the server.

      For each server host, the scratch directory must be created for staging in advance.

      The staging directory is "$HOME/.globus/scratch" ($GLOBUS_SCRATCH_DIR variable in GT4 GRAM RSL).

      Please create the directory as follows:

      
% mkdir ~/.globus/scratch
% chmod 700 ~/.globus/scratch

4.4.2 Invoke Server SSH

Invoke Server SSH invokes Ninf-G Executable via SSH.

  1. Prerequisite

    User must be able to execute commands on the server using ssh command. In addition, it is recommended to configure user's ssh environments not to require user's input (e.g. password) for executions to avoid repetitious input while Ninf-G application is executed. "ssh-agent" and "ssh-add" commands are usually used for such purposes.

    The following commands are required by Invoke Server SSH and must be available on the server.

    /bin/sh, /bin/echo, /bin/grep, /bin/chmod, /bin/mkdir, /bin/cat, /bin/rm, /bin/kill

  2. Install

    Invoke Server SSH is automatically installed through the Ninf-G installation processes described in section 2 of this manual.

  3. Job submission system

    Like Globus GRAM, Invoke Server SSH is able to launch remote processes via a backend queuing system including SGE and PBS(*1). The backend queuing system is specified by "jobmanager" attribute in <SERVER> section in the Ninf-G Client Configuration file. The value of "jobmanager" attribute can be either "jobmanager-sge" for SGE or "jobmanager-pbs" for PBS.

    Example: 
    
<SERVER>
   hostname example.org
   invoke_server SSH
   jobmanager jobmanager-sge
      :
      :
</SERVER>

    It should be noted that although the values "jobmanager-sge" and "jobmanager-pbs" are also used for Invoke Servers for Globus GRAM (e.g. GT4py), jobmanager programs used by Invoke Server SSH are implemented by the Ninf-G development team hence they are completely different with the jobmanager programs provided by the Globus Toolkit.

    The jobmanager program assumes that user's home directory is shared between front (master) node and compute nodes.

    Invoke Server SSH uses qsub, qstat, and qdel commands in jobmanager-sge and jobmanager-pbs. Therefore, the path of these commands should be included in PATH environment variable. Otherwise, the path of these commands must be passed by options described below.

    CommandOption
    qsubssh_submitCommand
    qstatssh_statusCommand
    qdelssh_deleteCommand

    The detailed description of these options is described in section 4.4.2.4 of this manual.

    (*1) Invoke Server SSH is tested with PBS Pro and Torque.

  4. Extra options

    Invoke Server SSH accepts the following extra options.

4.4.3 Invoke Server Condor

Invoke Server Condor invokes Ninf-G Executable via Condor(*1).

*1 Condor Project: http://www.cs.wisc.edu/condor/

  1. Prerequisite

  2. Install

    Invoke Server Condor is not installed by the default Ninf-G installation and it must additionally installed manually according to the following steps.

    1. Set the NG_DIR environment variable 

      
csh.
% setenv NG_DIR /path/to/ninf-g

sh.
$ NG_DIR=/path/to/ninf-g ; export NG_DIR

    2. Change directory to the directory of Invoke Server Condor. 

      
% cd ng-4.x.x  # expanded Ninf-G package
% cd utility/invoke_server/condor

    3. Run "make" command to compile Invoke Server Condor 

      
% make

    4. Run "make install" command to install Invoke Server Condor 

      
% make install

      This command copies the following files under ${NG_DIR} directory.

      ${NG_DIR}/lib/

      • classad.jar - Log analysis library for Condor Job
      • condorAPI.jar - Condor Java API Library
      • condorIS.jar - Invoke Server Condor

      ${NG_DIR}/bin/

      • ng_invoke_server.Condor - Startup script for Invoke Server Condor

  3. Extra options

    none

  4. Information

    Invoke Server Condor automatically creates the Condor job cluster log when it invokes jobs. The name of the log file is "ninfg-invoke-server-condor-log".

  5. Limitation

4.4.4 Invoke Server NAREGISS

Invoke Server NAREGISS invokes Ninf-G Executable via NAREGI Super Scheduler.

  1. Prerequisite

    NAREGI Middleware V1.1 or later is required. Java 1.5.0 or later.

  2. Install

    Invoke Server NAREGISS can be installed as a part of Ninf-G installation steps. Invoke Server NAREGISS is installed if --with-naregi is specified as a Ninf-G configure script option.

    Example: 

    
% ./configure --with-naregi

    NOTE: If NAREGI Middleware is not installed in default the directory (/usr/naregi), it is necessary to specify it with configuration option "--with-naregidir".

    Details of Ninf-G configure script are described in 2.4 Configure command options.

  3. Note

    Invoke Server NAREGISS assumes that the Ninf-G Client is invoked as a job via NAREGI SS, and expects the followings.

  4. Extra options

    Invoke Server NAREGISS accepts the following extra options.

  5. Known Problems

    Invoke Server NAREGISS has some problems. Details are described in 11.5 Problems related to NAREGI SS.

4.5 Running the Ninf-G Client program

4.6 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 a 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 created 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 create 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 used 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 the sending of 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. Destruction of handles

    For releasing resources, 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 termination processing.

    grpc_error_t grpc_finalize()

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

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

appendix

a.1 : How to use multiple user certificates

Ninf-G Client is able to use multiple user proxy certificates. Being enabled by Invoke Server, this capability is useful for using different user proxy certificates according to the security configuration (accepted CAs) of servers.

This section describes how to use multiple certificates.

a.1.1 Create a script which specifies a user proxy certificates used for user authentication by the server. It is recommended to create a script using a template provided by Ninf-G.

Copy the script from template ($NG_DIR/etc/ng_invoke_server.GTtempl).

% cp $NG_DIR/etc/ng_invoke_server.GTtempl $NG_DIR/bin/ng_invoke_server.GT4cert1 
% chmod u+x $NG_DIR/bin/ng_invoke_server.GT4cert1

Modify the copied script in which you have to specify the user proxy certificate(*1) and the script file(*2) which you will use. 

#! /bin/sh

X509_USER_PROXY=/path/to/x509up_xxxx <- (*1)
export X509_USER_PROXY
exec $NG_DIR/bin/ng_invoke_server.GT4py <- (*2)

a.1.2 Modify the client configuration file

Modify the client configuration file and specify the Invoke Server that you created at a.1.1. 

<SERVER>
    hostname  example.org
        :
    invoke_server  GT4cert1
</SERVER>

a.2 : How to implement cascading RPC

Ninf-G4 supports cascading RPC, which enables Ninf-G Executable to call GridRPC API. Cascading RPC is realized by (1) implementing remote functions that calls GridRPC API (server-side implementation) and (2) configuring Ninf-G client to enable delegation of full-proxy certificates (client-side configuration).

  1. Server-side implementation

    In the IDL file,

  2. Client-side configuration

Note: Cascading RPC is available for Ninf-G Version 4.2.0 or later.

last update : $Date: 2008/09/12 08:27:42 $