CCARD(3)                         RPN UTILITY                          CCARD(3)

NAME 
        ccard, c_ccard - gather and process program arguments.

DESCRIPTION
        ccard is  a  module (a  fortran  subroutine  or a  C  function)  which
provides to a FORTRAN or C  program a standard mechanism for the  recuperation
and treatment of call-time arguments. With ccard, a call to a program has  the
following format:

        progname [pos ...] -key1 [val1 ...] -key2 [val2 ...] ... [-- pos ...]

        where progname  - is the name of the program to call
              pos       - represents a positional argument 
              keyi      - is a symbolic name or key name
              vali      - is the value given to a symbolic name 
              --        - used to indicate that  the following parameters  are
                          to be treated as positional arguments.

USAGE 
      FORTRAN:    CALL CCARD(LISTE,DEF,VAL,N,NPOS)

      C      :    void c_ccard();
                  c_ccard(argv,argc,liste,val,def,n,&npos);

ARGUMENT DEFINITION 

FORTRAN:    CHARACTER*(*) LISTE(N), DEF(N), VAL(N)
            INTEGER N, NPOS

C:          char **argv, *liste[n], *def[n], val[n][256]; 
            int argc, n, *npos;

LISTE       (INPUT)
            Array containing the name  of the various keys.   By default,  the
            value assigned to a key will be converted to capital letters.   If
            a key name is terminated by an underscore (_), the value  assigned
            to that key  will be converted  to lower case  letters.  Ending  a
            key name with a  period (.), will force  ccard to leave the  value
            untouched.   These  extra  characters are  used  only  inside  the
            program in  the  LISTE  array  in order  to  define  the  type  of
            treatment to perform on  the value given to  a certain key.   They
            must not appear in a program calling sequence.

            With ccard,  it  is possible  to  simulate a  positional  mode  of
            argument recuperation by  using the reserved  key name '-'  (minus
            sign) in LISTE.  An argument is said to be positional if it is not
            associated to a key name on the command line. (See the example)

VAL         (INPUT/OUTPUT) 
            On input, this array  contains the initial  values of the  various
            keys (first default value).  On output, the VAL array contains the
            final values of the  keys. The value  of a key  is found by  first
            locating a key  name in LISTE  and then finding  the value in  the
            corresponding position in the VAL array.

            If the name  of a key  is not  present in the  argument list,  the
            initial value contained in VAL will be returned as the final value
            for the key.  The presence of a key name with no associated  value
            on the calling card causes ccard  to copy the contents of the  DEF
            array, at the location  given by the position  of the key name  in
            LISTE, to the corresponding position in  the VAL array.  If a  key
            name is followed by  a value, it is  the user supplied value  that
            will be copied to VAL at the appropriate position.

DEF         (INPUT)
            Array containing the second default value to give to a key.  If on
            the program calling card the name  of a key appears without  being
            followed by a value, the contents of DEF, at the position given by
            the key in LISTE, will be copied to the corresponding position  in
            the VAL array.

N           (INPUT)
            Number of keys to  initialize.  Length of  the LISTE, VAL and  DEF
            arrays.

NPOS        (INPUT/OUTPUT)
            On output, npos contains the number of positional parameters  that
            were present in the  argument list.  However,  this value is  only
            returned when npos is  greater than zero on  input.  If on  input,
            npos is less or equal to zero, its value will be left unchanged by
            ccard. Furthermore,  npos  =  -111  on  input,  informs  ccard  to
            immediately stop program execution upon encountering an error.

argv        (INPUT)
            Array of pointers to the argument list of a C program.

argc        (INPUT)
            Number of arguments supplied to a C program. Length of argv.

EXAMPLE
        To illustrate  the use  of ccard,  we will  write   a FORTRAN  program
called AFFICHE, which does nothing  but print the final   values given to  its
keys as well as the positional parameters it received as arguments.

        Comments: -note that key name CLE1 is followed  by   a  period,   thus
                   indicating that no character conversion is to be  performed
                   on its value. 
                  -both occurrences  of CLE2  are not  followed by  a  special
                   character so that  the values  they will be  given will  be
                   converted to upper case.
                  -the final value  of CLE3  will be converted  to lower  case
                   letters since CLE3 is terminated by an underscore.
                  -note finally that since NPOS is set to a value greater than
                   zero on input, ccard will  return the number of  positional
                   parameters present in the program call argument list.
    ___________________________________________________________________
   |                                                                   |
   |      PROGRAM AFFICHE                                              |
   |                                                                   |
   |      EXTERNAL CCARD                                               |
   |                                                                   |
   |      CHARACTER*8 LISTE(6), DEF(6), VAL(6)                         |
   |                                                                   |
   |      INTEGER NPOS                                                 |
   |                                                                   |
   |*     NO CONVERSION FOR THE VALUE OF CLE1                          |
   |*     CONVERT VALUES OF CLE2 TO UPPER CASE LETTERS                 |
   |*     CONVERT VALUE OF CLE3 TO LOWER CASE LETTERS                  |
   |                                                                   |
   |      DATA LISTE /'CLE1.','CLE2','CLE2',  'CLE3_','-','-'/         |
   |                                                                   |
   |      DATA VAL   /'Val11','VAL21','VAL22','val31',' ',' '/         |
   |                                                                   |
   |      DATA DEF   /'Def11','DEF21','DEF22','def31',' ',' '/         |
   |                                                                   |
   |      NPOS = 1                                                     |
   |      CALL CCARD(LISTE,DEF,VAL,6,NPOS)                             |
   |                                                                   |
   |      WRITE(6,*)' NUMBER OF POSITIONAL PARAMETERS :',NPOS          |
   |      WRITE(6,*)VAL(5), VAL(6)                                     |
   |      WRITE(6,*)' CLE1 = ',VAL(1)                                  |
   |      WRITE(6,*)' CLE2 = ',VAL(2), VAL(3)                          |
   |      WRITE(6,*)' CLE3 = ',VAL(4)                                  |
   |                                                                   |
   |      STOP                                                         |
   |      END                                                          |
   |___________________________________________________________________|

        Here, we have a few  calling sequences to the AFFICHE program.

     Call:       AFFICHE

     Result:     NUMBER OF POSITIONAL PARAMETERS : 0

                 CLE1 = Val11
                 CLE2 = VAL21  VAL22 
                 CLE3 = val31

     Call:       AFFICHE -- pos1 pos2

     Result:     NUMBER OF POSITIONAL PARAMETERS : 2 
                 POS1    POS2
                 CLE1 = Val11
                 CLE2 = VAL21   VAL22
                 CLE3 = val31

     Call:       AFFICHE -CLE1 -CLE2 -CLE3

     Result:     NUMBER OF POSITIONAL PARAMETERS : 0

                 CLE1 = Def11
                 CLE2 = DEF21   DEF22
                 CLE3 = def31

     Call:       AFFICHE -CLE1 Tape1 -CLE2 Tape2 Tape3 -cle3 Tape4

     Result:     NUMBER OF POSITIONAL PARAMETERS : 0

                 CLE1 = Tape1
                 CLE2 = TAPE2   TAPE3
                 CLE3 = tape4

     Call:       AFFICHE debug -CLE2 =-12:33

     Result:     NUMBER OF POSITIONAL PARAMETERS : 1 
                 DEBUG
                 CLE1 = Val11
                 CLE2 = -12     33
                 CLE3 = val31

     Call:       AFFICHE pos1 -- pos2

     Result:     NUMBER OF POSITIONAL PARAMETERS : 2 
                 POS1   POS2
                 CLE1 = Val11 
                 CLE2 = VAL21  VAL22 
                 CLE3 = val31

ASSIGNING A VALUE TO A KEY

        A key may  be given  a single value  or multiple  values separated  by
spaces or colons.  If a key is to receive a negative value, the value must  be
preceded by an equal sign.  This  allows ccard to differentiate between a  key
name (which is always  preceded by a minus  sign) and a  value. If a  negative
value is part  of colon separated  list and is  not the first  element of  the
list, the equal sign may be omitted.

        Values may be assigned to keys in the following fashions:

        -key value 
        -key "value" 
        -key 'value' 
        -key value1  value2 value3 
        -key value1:value2:value3 
        -key=value1:value2:value3

        Examples:

        -key 10 =-12 =-34 45
        -key 10:-12:-34:45
        -key =-12:10:-34:45
        -key=-12:10:-34:45

NOTES 
        1:   In order to be able to assign  multiple values to a key, the  key
             must be defined as a list in the LISTE array.  If for example,  a
             key named cle1, is to receive three values, that key name must be
             present in three consecutive locations in the LISTE array:

             DATA LISTE /'CLE1','CLE1','CLE1'/

             thus allowing a program call of the form:

             progname -cle1 value1 value2 value3

        2:   The rule stated in NOTE  1 also applies to positional  arguments.
             The LISTE array must contain  n contiguous references to the  key
             '-' in order to pass n positional arguments to a program:

             DATA LISTE /'-','-','-', ... /

        3:   Any repeated key name of the  LISTE array may be terminated by  a
             conversion character  (_ or  .) that  is different  from the  one
             given to other  keys of the  same name.   One could for  instance
             force the first value of key1 to lower case letters while leaving
             the other values to upper case:

             DATA LISTE /'key1_','key1','key1'... /

        4:   ccard converts all key names  to upper case letters.   Therefore,
             calling a  program  using '-KEY1  value'  is the  same  as  using
             '-key1 value'

        5:   Any program using ccard will print its calling sequence if it  is
             invoked with the -h key:

                affiche -h

             will yield:

                affiche 
                       -CLE1 [Val11:Def11] 
                       -CLE2 [VAL21:DEF21] 
                       -CLE2 [VAL22:DEF22]
                       -CLE3 [val31:def31]
                       --    [ : ]
                       --    [ : ]

             Note that there is no need to have an element of the LISTE  array
             initialized to 'H' for this to work.

AUTHORS 
        M.Valin, M. Lepine, J. Caveen - RPN
        Latest revision: January 1993