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