3 Creating and setting up server-side programs

3.1 Creating a Ninf-G Executable

• Describing the interface information with Ninf-G IDL

  The following kinds of information are described with IDL.

  • Module name (Ninf-G Executable identifier)
  • Interface information
  • Other information required by Ninf-G Executable

  The following is a sample of IDL for implementing matrix multiplication. For detailed Ninf-G IDL specifications, see chapter 6, "Ninf-G IDL Specifications".

  Ninf-G IDL sample

  Module mmul; Define dmmul(IN int n, IN double A[n][n], IN double B[n][n], OUT double C[n][n]) "... description ..." Required "libxxx.o" /* specify library including this routine. */ Calls "C" mmul(n,A,B,C); /* Use C calling convention. */

  The following is an example of a "callback", that can be described with Ninf-G IDL.

  Ninf-G IDL sample (callback)

  Module test; Define callback_test(IN int a, OUT int *b, callback_func(IN int c[1], OUT int d[1])) { int executableStatus, clientStatus; executableStatus = calc(a, b); callback_func(executableStatus, &clientStatus); if (d == 1) { /* client is alive */ } }

  Note: You may find some compiler warnings when you compile Callback function, but they are harmless. For example, following compiler warning is output by Solaris/vendor-cc.

  "warning: old-style declaration or incorrect type for: callback_test"

• Implementation of remote functions and remote methods

  The required remote functions and remote methods (those called in the IDL) must be implemented (in C or FORTRAN).

  The source code (C) for the mmul() function used in the Ninf-G IDL sample shown above is presented below.

  Remote function (Remote method) sample

  void mmul(int n, double * a, double * b, double * c) { double t; int i, j, k; for (i = 0; i < n; i++) { for (j = 0; j < n; j++) { t = 0; for (k = 0; k < n; k++){ t += a[i * n + k] * b[k * n + j]; } c[i * n + j] = t; } } }

  Note: Implementing cancel processing

  When implementing processing for canceling a session, call grpc_is_canceled_np() in the Ninf-G Executable Library API from within a remote function or remote method and check the return value. Coding for performing session cancel processing if the return value is 1 is needed.

  Example of cancel processing implementation

  #include <grpc_executable.h> void mmul(int n, double * a, double * b, double * c) { double t; int i, j, k; for (i = 0; i < n; i++) { for (j = 0; j < n; j++) { t = 0; for (k = 0; k < n; k++){ t += a[i * n + k] * b[k * n + j]; } c[i * n + j] = t; } if (grpc_is_canceled_np() == 1) { /* canceled */ break; } } }

  
  
• Using the Ninf-G generator to compile the IDL

  % ${NG_DIR}/bin/ng_gen

  Executing the above command generates the following.

  • Ninf-G stub for executing a remote function (remote method)
  • makefile for generating a Ninf-G Executable
  • LDIF file (for saving the interface information)
  • Local LDIF file (for saving the interface information)
  
  
• Creating the Ninf-G Executable

  The makefile generated by the stub generator is used to execute the make command.

  % make -f <module_name>.mak

  An executable Ninf-G Executable is generated.

  (The following tasks are not necessary if MDS is not being used. The Ninf-G Executable information can be acquired without MDS by using the Ninf-G Executable path information that is contained in the local LDIF file on the client side or in the Ninf-G Client configuration file.)

• Copying the LDIF file to the specified location

  The LDIF file generated by the stub generator is copied to $GLOBUS_LOCATION/var/gridrpc.

  % make -f <module_name>.mak install

  The content of the copied LDIF file is shown below.

  Example LDIF file

  dn: GridRPC-Funcname=mmul/dmmul, Mds-Software-deployment=GridRPC-Ninf-G, objectClass: GlobusSoftware objectClass: MdsSoftware objectClass: GridRPCEntry Mds-Software-deployment: GridRPC-Ninf-G GridRPC-Funcname: mmul/dmmul GridRPC-Module: mmul GridRPC-Entry: dmmul GridRPC-Path: /path/to/_stub_dmmul GridRPC-Stub:: ICA8Y2xhc3MgbmFtZT0ibW11bC9kbW11bCIgdmVyc2lvbj0iMS4wIiBud ...

  Note: Copying the LDIF file to the prescribed location as above enables provision of Ninf-G Executable information by MDS.

  Ninf-G provides utility commands (described below) for managing the Ninf-G Executable information supplied by MDS. Details on the commands can be found in chapter 8, "Utility Command Reference".

  • Display the Ninf-G Executable information provided by the MDS of the host. (the ng_dump_functions command)
  • Delete the Ninf-G Executable information from MDS (the ng_delete_functions command)

3.2 Setting up the Ninf-G Executable operating environment

• Preparing the configuration file for use by Ninf-G Executable

  Prepared according to the need for a configuration file for adjusting the location of the temporary files generated during filename type argument processing and for the log output.

  • System settings

    Written in ${GLOBUS_LOCATION}/var/gridrpc/ngstub.conf.

  • User settings

    Write ".ngstubrc" in the user's home directory.

  If the system settings and user settings described above both have the same setting items, the user settings have priority.

3.3 Specifications for the configuration file used by Ninf-G Executable

3.3.1 Structure of the configuration file

The Ninf-G Executable configuration file is a text file which contains the settings information that is required for operation of Ninf-G Executable.

• This file is placed on the server on which Ninf-G Executable runs.
• The system attribute file is located in $GLOBUS_LOCATION/var/gridrpc/. The file name is ngstub.conf.
• The user definition file (user settings file) is placed in the user's home directory. The file name is .ngstubrc.
• If the user wants to change a system attribute, the attribute to be changed is written in the user definition file.

An example of entries in the Ninf-G Executable configuration file is shown below.

#comment

attribute    value    # comment

attribute    value    # comment
attribute    value    # comment

...

• Each line consists of an attribute and its value.
• One line defines one attribute.
• What follows after a pound sign (#) is interpreted as a comment.
• The attribute and attribute value must be separated by one or more spaces or by a TAB character.
• Multiple attributes cannot be written on one line.
• The attribute and attribute value must be written on the same line.
• One attribute definition cannot extend over more than one line.
• An attribute must have a defining attribute value. An attribute alone defines nothing.
• Attribute values of attributes for which multiple definitions are possible cannot overlap.

The following description produces an error.

AttributeValue
        #  No delimiter between attribute and attribute value

Attribute    Value    Attribute    Value
        # Multiple attributes on a line

Attribute
Value
        #  attribute value extend across more than one line

Attribute
        #  No attribute value

tmp_dir /tmp
tmp_dir /var/tmp
        # Overlapping of the attribute values of an attribute
        #  that can not have multiple definitions

3.3.2 Attributes and attribute values

The attributes and their attribute value definitions are listed below.

tmp_dir                        Directory
loglevel                       [0-5]
loglevel_globusToolkit         [0-5]
loglevel_ninfgProtocol         [0-5]
loglevel_ninfgInternal         [0-5]
log_filePath                   File name
log_suffix                     Suffix
log_nFiles                     Number of files
log_maxFileSize                Number of bytes
log_overwriteDirectory         [true/false]
commLog_enable                 [true/false]
commLog_filePath               PathFile name
commLog_suffix                 Suffix
commLog_nFiles                 FilesNumber of files
commLog_maxFileSize            FileSizeNumber of bytes
commLog_overwriteDirectory     [true/false]
save_stdout                    File name
save_stderr                    File name

The definable attributes and attribute values are listed below.

The meanings of the log level values are described below.

• tmp_dir(temporary file directory)

  The directory in which temporal files are placed for passing the filename type arguments to a remote method.

  When omitted, if TMPDIR environment variable is defined, it is used; otherwise, "/tmp" is used.

• loglevel*(log level)

  The log level is specified for all log categories by loglevel and for each category individually by loglevel_*.

  When the log level for each category has not been specified, the log level for all categories is applied.

  When omitted, the value of NG_LOG_LEVEL environment variable is used.
  If NG_LOG_LEVEL environment variable is not set, 2 (Error) is used as the default value of loglevel.

• log_filePath(log file name)

  The name of the file to which the log is output is specified in the log file name.

  The file name may include a path that includes a directory (e.g., "/home/myHome/var/logFile").

  The file and directory name can include the following specifiers.

  • "%t"

    "%t" is replaced with the date as year, month and day, and the time in hours, minutes, seconds and milliseconds ("yyyymmdd-hhmmss-MMM") (e.g., "/ home/myHome/var/logDir%t/logFile" is replaced by "/home/myHome/var/logDir20030101-154801-123/logFile").

  • "%h"

    "%h" is replaced with the Ninf-G Executable hostname.

  • "%p"

    "%p" is replaced with the process id of Ninf-G Executable.

  The Ninf-G Executable id number is added to the end of the file name.

  When omitted, the log is output to standard error. If the log file name is omitted, the log_suffix, log_nFiles and log_maxFileSize are ignored.

  Note: When the Ninf-G Executable exits abnormally on startup, the executable id is not added and the hostname and process id are added to the end of the file name.

• log_suffix(log file suffix)

  When a log file is specified, this specifies the suffix for when the log file is created.

  If a suffix is specified, the generated file name will be from "filename[000].suffix" to "filename[nnn].suffix". If omitted, the generated file name will be from "filename.[000]" to "filename.[nnn]". The number of files minus 1 is "nnn".

  The number of digits in "nnn" is the same as the number of digits in number of files minus 1. For example, if the number of files is set to 100, then the number will range from "00" to "99".

• log_nFiles(the number of files for log output)

  This is the number of files created for log output.

  0 indicates to output unlimited number of files. An negative value results in an error.

  If omitted, the value 1 is used.

• log_maxFileSize(maximum number of bytes for the log file)

  This is the maximum number of bytes for the log file. A unit indicator from among "kKmMgG" can be appended to the numerical value to indicate Kilobytes (1024 bytes), Megabytes (1024 Kbytes), or Gigabytes (1024 Mbytes).

  If omitted, the value will be unlimited if the number of files is one or 1 Mbyte if the number of files is two or more.

• log_overwriteDirectory (over-write permission for the directory in which the log files are generated)

  This establishes overwrite permission for the directory. If the specified directory exists, this specifies whether the creation of log files in that directory is enabled or disabled.

  The operation in the case that the directory exists is shown below.

  • true: If the file specified by log_filePath exists in the directory, that file is overwritten.
  • false: Error.

• commLog_enable (whether communication log output is enabled or disabled)

  This specifies whether the communication log output function is enabled or disabled. If 'true' is specified, the communication log is output. If not specified, the default value is false.

• commLog_filePath(communication log file name)

  The name of the file to which the communication log is output is specified in the log file name.

  The file name may include a path that includes a directory (e.g., "/home/myHome/var/logFile").

  The file and directory name can include the following specifiers.

  • "%t"

    "%t" is replaced with the date as year, month and day, and the time in hours, minutes, seconds and milliseconds ("yyyymmdd-hhmmss-MMM") (e.g., "/ home/myHome/var/logDir%t/logFile" is replaced by "/home/myHome/var/logDir20030101-154801-123/logFile").

  • "%h"

    "%h" is replaced with the Ninf-G Executable hostname.

  • "%p"

    "%p" is replaced with the process id of Ninf-G Executable.

  The Ninf-G Executable id number is added to the end of the file name.

  When omitted, the log is output to standard error. If the communication log file name is omitted, the commLog_suffix, commLog_nFiles and commLog_maxFileSize are ignored.

• commLog_suffix(communication log file suffix)

  When the communication log file is specified, this specifies the suffix for when the log file is created.

  If a suffix is specified, the generated file name will be from "filename[000].suffix" to "filename[nnn].suffix". If omitted, the generated file name will be from "filename.[000]" to "filename.[nnn]". The number of files minus 1 is "nnn".

  The number of digits in "nnn" is the same as the number of digits in the number of files minus 1. For example, if the number of files is set to 100, then the number will range from "00" to "99".

• commLog_nFiles(number of files for communication log output)

  This is the number of files created for communication log output.

  0 indicates to output unlimited number of files. An negative value results in an error.

  If omitted, the value 1 is used.

• commLog_maxFileSize (maximum number of bytes for the communication log file)

  This specifies the maximum number of bytes for the communication log file. A unit indicator from among "kKmMgG" can be appended to the numerical value to indicate Kilobytes (1024 bytes), Megabytes (1024 Kbytes), or Gigabytes (1024 Mbytes).

  If omitted, the value is either unlimited if the number of files is one or 1 Mbyte if the number of files is two or more.

• commLog_overwriteDirectory (over-write permission for the directory in which the communication log files are generated)

  This establishes overwrite permission for the directory. If the specified directory exists, this specifies whether the creation of log files in that directory is enabled or disabled. The operation in the case that the directory exists is shown below.

  • true: If the file specified by log_filePath exists in the directory, that file is overwritten.
  • false: Error.

• save_stdout (Save stdout to file)

  This specifies the file name to save stdout.

  If this attribute is set, stdout is saved to the specified file.

  If the given file name for both save_stdout and save_stderr attribute is the same, output is shared to one file in arbitrary order.

  The output file is opend by append mode.

  If omitted, stdout output is delivered to Ninf-G Client or discarded.

• save_stderr (Save stderr to file)

  This specifies the file name to save stderr.

  If this attribute is set, stderr is saved to the specified file.

  If the given file name for both save_stdout and save_stderr attribute is the same, output is shared to one file in arbitrary order.

  The output file is opend by append mode.

  If omitted, stderr output is delivered to Ninf-G Client or discarded.