wiki:DocDéveloppeur

Version 5 (modified by sdipsl, 16 years ago) (diff)

--


Documentation Développeur

Auteurs : Sébastien Denvil, Martial Mancip, Patrick Brockmann


Sommaire général libIGCM

Table des matières

  1. Stratégies de développement
  2. Règles de syntaxe
  3. libIGCM_card
    1. Description du format card
    2. Documentation interne
  4. libIGCM_comp
  5. libIGCM_config
  6. libIGCM_date
    1. Documentation interne
  7. libIGCM_debug
    1. Documentation interne
  8. libIGCM_post
  9. libIGCM_sys


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: