----
'''''Documentation Développeur'''''

'''Auteurs''' : Sébastien Denvil, Martial Mancip, Patrick Brockmann [[BR]]
----

'''Sommaire général''' [wiki:WikiStart libIGCM]
[[PageOutline(1-2,Table des matières,inline)]]

----

= Stratégies de développement =
 * Développer le plus clairement possible
 * S'appuyer sur des commandes UNIX avec des options standards
 * Inclure une documentation dans le code

{{{
#==================================================
# The documentation of this file can be automatically generated
# if you use the prefix #D- for comments to be extracted.
# Extract with command: cat lib* | grep "^#D-" | cut -c "4-"
#==================================================
#D-This line will be extracted
#D-This one too
}}}
 * Fournir une fonction de test pour chaque librairie. Le test se réalise en faisant la différence entre les résulats courants et un fichier de résultats de référence. 

{{{
Check libIGCM_debug ..........................................[ FAILED ]
}}}
Indique que la librairie libIGCM_debug n'est pas opérationnelle.
{{{
Check libIGCM_debug ..............................................[ OK ]
Check libIGCM_card ...............................................[ OK ]
Check libIGCM_date ...............................................[ OK ]
}}}
Indique que toutes ces librairies sont opérationnelles.

= Règles de syntaxe =
 * Les noms des variables sont définies sans espace avec des majuscules :
  * ceciestunevariable <-- incorrect
  * !CeciEstUneVariable <-- correct

= libIGCM_card =

Cette librairie se charge de faire la lecture et l'écriture dans les fichiers
carte.

== Description du format card ==

Ce paragraphe décrit les éléments du format d'un fichier CARD (inspiré du format INI):

 * Sections: Les sections commencent par ''['' et se termine par '']'' comme pour les sections [Messages] et [Recipes]  utilisées dans l'exemple ci-dessous.

 * Options: L'option ''Red = 120'' ci-dessous est un exemple d'option (aussi connu sous le nom de clé). Les options commencent par une clé ''Red'', suivie du signe égale '=', et elles se terminent par une valeur ''120''.

 * Commentaires: Toutes les lignes commençant par un '#' sont considérées comme étant des commentaires, et sont ignorées.

 * Continuation de lignes: Une option peut être écrite sur plusieurs lignes si le dernier caractère de la ligne est un '\'

 * Exemple:

{{{
[Messages]
Option1= "Hello Earth"
Option2= "Hello Mars"

# My comments
[Recipes]
Cake= "file1.doc"
Starter= "file2.doc"

[ColorValues]
Red= 120
Blue= 230
Green= 178

[Couples]
List1=   (up, down), \
         (humid, dry), \
         (hot, cold), \
         (far, close)
List2=   (ice, fire, air, water)
}}}

== Documentation interne ==

{{{
#==================================================================
libIGCM_card
This ksh library handles extraction of information from configuration file
called "card" file (en français fichier "carte").
All function described bellow must be prefixed by IGCM_card.

#==================================================================
function IGCM_card_PrintOption
* Purpose: Print an option from a given file.card and section
* Usage: IGCM_card_PrintOption file.card section option

#==================================================================
function IGCM_card_PrintSection
* Purpose: Print all options from a given file.card and section
* Usage: IGCM_card_PrintSection file.card section

#==================================================================
function IGCM_card_DefineVariableFromOption
* Purpose: Define a variable from a given file.card, section and option
*          Variable name is automatically defined as file_section_option
* Usage: IGCM_card_DefineVariableFromOption file.card section option

#==================================================================
function IGCM_card_DefineArrayFromOption
* Purpose: Define an array variable from a given file.card, section and option
*          Array variable is automatically defined as file_section_option
* Usage: IGCM_card_DefineArrayFromOption file.card section option

#==================================================================
function IGCM_card_DefineArrayFromSection
* Purpose: Define an array variable from a given file.card and section
*          Array variable is automatically defined as file_section
* Usage: IGCM_card_DefineArrayFromSection file.card section

#==================================================================
function IGCM_card_WriteOption
* Purpose: Write an option from a given file.card and section
* Usage: IGCM_card_WriteOption file.card section newvalue
* Examples: IGCM_card_WriteOption file.card Recipes Red 150
            IGCM_card_WriteOption file.card Messages Option2 '"Hello Mercure"'
            IGCM_card_WriteOption file.card Messages ListVal1 '( 1, 2, 3 )'
            listname="(Sebastien, Martial, Patrick)"
            IGCM_card_WriteOption NewTestFile.card Messages ListVal2 "${listname}"

#==================================================================
function IGCM_card_Check
* Purpose: Check the present file by comparison with a reference file
* Usage: IGCM_card_Check
}}}

= libIGCM_comp =

= libIGCM_config =

= libIGCM_date =

== Documentation interne ==
{{{
#==================================================================
libIGCM_date
This ksh library handles date calculs and convertions in different calendars.

#==================================================================
function IGCM_date_DaysInYear
 * Purpose: Return the number of days in a year
 * Usage: IGCM_date_DaysInYear yyyy
          if there is no argument on the command line,
          then assume that a yyyy is being piped in

#==================================================================
function IGCM_date_DaysInMonth
 * Purpose: Calculate the number of days in a month
 * Usage: IGCM_date_DaysInMonth yyyy mm
          or IGCM_date_DaysInMonth yyyymmdd
          if there are no command line arguments then
          assume that a yyyymmdd is being piped in and read the value.
          if there is only one argument assume it is a yyyymmdd on the command line
          other wise it is a yyyy and mm on the command line

#==================================================================
function IGCM_date_ConvertGregorianDateToJulian
 * Purpose: Convert yyyymmdd to yyyyddd
 * Usage: IGCM_date_ConvertGregorianDateToJulian 19980429
          if there is no command line argument, then assume that the date"
          is coming in on a pipe and use read to collect it

#==================================================================
function IGCM_date_ConvertJulianDateToGregorian()
 * Purpose: Convert yyyyddd to yyyymmdd
 * Usage: IGCM_date_ConvertJulianDateToGregorian 1998213
          if there is no command line argument, assume one is being
          piped in and read it

#==================================================================
function IGCM_date_AddDaysToJulianDate
 * Purpose: Add days to a yyyyddd formatted date
 * Usage: IGCM_date_AddDaysToJulianDate 1998312 { ,-}14
          Read from the difference from the command lines
          and the date from the command line, or standard input

#==================================================================
function IGCM_date_AddDaysToGregorianDate
 * Purpose: Add days to a yyyymmdd formatted date
 * Usage: IGCM_date_AddDaysToGregorianDate 19980312 { ,-}14
          Read from the difference from the command lines
          and the date from the command line, or standard input

#==================================================================
function IGCM_date_DaysBetweenJulianDate
 * Purpose: Calculate the days difference between two dates and reports
            the number days as jul1 - jul2
 * Usage: IGCM_date_DaysBetweenJulianDate jul1 jul2
          where julian date is in the form yyyyddd

#==================================================================
function IGCM_date_DaysBetweenGregorianDate ()
 * Purpose: Calculate the days difference between two dates and reports
            the number days as grg1 - grg2
 * Usage: IGCM_date_DaysBetweenGregorianDate grg1 grg2
          where gregorian date is in the form yyyymmdd

#==================================================================
function IGCM_date_DaysSinceJC ()
 * Purpose: Calculate the days difference between a date and 00010101
 * Usage: IGCM_date_DaysSinceJC grg1
          where gregorian date is in the form yyyymmdd

#==================================================================
function IGCM_date_Check
 * Purpose: Check the present file by comparison with a reference file
}}}

= libIGCM_debug =

== Documentation interne ==

{{{
#==================================================================
function IGCM_debug_CallStack
* Purpose: Echo the Stack

#==================================================================
function IGCM_debug_PushStack
* Purpose: Push a function name in the stack

#==================================================================
function IGCM_debug_PopStack
* Purpose: Pop a function name in the stack

#==================================================================
function IGCM_debug_Exit
* Purpose: Print Call Stack and set ExitFlag to true

#==================================================
function IGCM_debug_Verif_Exit
* Purpose: exit with number 1 if ExitFlag is true

#==================================================
function IGCM_debug_Verif_Exit_Post
* Purpose: exit with number 1 if ExitFlag is true for Post-treatment

#==================================================================
function IGCM_debug_Print
* Purpose: Print arguments according to a level of verbosity.

#==================================================================
function IGCM_debug_PrintVariables
* Purpose: Print arguments when match a pattern
           according to a level of verbosity.
#==================================================================
function IGCM_debug_Check
 * Purpose: Check the present file by comparison with a reference file
}}}

= libIGCM_post =

= libIGCM_sys =
{{{
#==================================================
LibIGCM_sys for Mercure
#==================================================

 This ksh library if a layer under some usefull 
environment variables and shell commands.
All those definitions depend on host particularities.
It manages a stack mechanism and test validity of operations.
All function described bellow must be prefixed by IGCM_sys.

#==================================================
Program used in libIGCM
#==================================================
#==================================================
function IGCM_sys_RshPost
* Purpose: Master rsh command
* Examples:

#==================================================
function IGCM_sys_Mkdir
* Purpose: Master locale mkdir command
* Examples:

#==================================================
function IGCM_sys_MkdirArchive
* Purpose: Mkdir on Archive
* Examples:

#==================================================
function IGCM_sys_MkdirWork
* Purpose: Mkdir on Work
* Examples:

#==================================================
function IGCM_sys_Cd
* Purpose: master cd command
* Examples:

#==================================================
function IGCM_sys_Chmod
* Purpose: Chmod
* Examples:

#==================================================
function IGCM_sys_FileSize
* Purpose: Filesize
* Examples:

#==================================================
function IGCM_sys_TestDir
* Purpose: Test Directory that must exists
* Examples:

#==================================================
function IGCM_sys_TestDirArchive
* Purpose: Test Directory that must exists on Archive
* Examples:

#==================================================
function IGCM_sys_TestFileArchive
* Purpose: Test file that must NOT EXISTS on Archive
* Examples:

#==================================================
function IGCM_sys_Tree
* Purpose: Tree directories with files on ${ARCHIVE}
* Examples: IGCM_sys_Tree ${R_IN} ${R_OUT}

#==================================================
function IGCM_sys_Tar
* Purpose: master un-tar command
* Examples:

#==================================================
function IGCM_sys_UnTar
* Purpose: master un-tar command
* Examples:

#==================================================
function IGCM_sys_Qsub
* Purpose: Qsub new job
* Examples:

#==================================================
function IGCM_sys_QsubPost
* Purpose: Qsub new job on scalaire
* Examples:

*************************
 File transfer functions 
*************************

#==================================================
function IGCM_sys_Rsync_out
* Purpose: treat return val of rsync
* Examples: IGCM_sys_Rsync_out out_RET_rsync
  Error values and explanations can depend on your system version.
#==================================================
function IGCM_sys_Cp
* Purpose: generic cp
* Examples:

#==================================================
function IGCM_sys_Mv
* Purpose: generic move
* Examples:

#==================================================
function IGCM_sys_Put_Rest
* Purpose: Put computied restarts on $(ARCHIVE).
           File and target directory must exist.
* Examples:

#==================================================
function IGCM_sys_Put_Out
* Purpose: Copy a file on $(ARCHIVE) after have chmod it in readonly
* Examples:

#==================================================
function IGCM_sys_Get
* Purpose: Get a file from ${ARCHIVE}
* Examples: IGCM_sys_Get myfile /destpath/myfile_with_PREFIX
            IGCM_sys_Get /l Array_contain_myfiles /destpath/

#==================================================
function IGCM_sys_GetDate_FichWork
* Purpose: donne la date filesys d'un fichier sur le filesystem WORK
* Examples:

#==================================================
function IGCM_sys_GetDate_FichArchive
* Purpose: donne la date filesys d'un fichier sur le filesystem ARCHIVE 
* Examples:
}}}