Actual source code: options.c

  1: /*$Id: options.c,v 1.252 2001/08/07 21:28:54 bsmith Exp $*/
  2: /*
  3:    These routines simplify the use of command line, file options, etc.,
  4:    and are used to manipulate the options database.

  6:   This file uses regular malloc and free because it cannot know 
  7:   what malloc is being used until it has already processed the input.
  8: */

 10:  #include petsc.h
 11:  #include petscsys.h
 12: #if defined(PETSC_HAVE_STDLIB_H)
 13: #include <stdlib.h>
 14: #endif
 15: #if defined(PETSC_HAVE_MALLOC_H) && !defined(__cplusplus)
 16: #include <malloc.h>
 17: #endif
 18: #if defined(PETSC_HAVE_SYS_PARAM_H)
 19: #include "sys/param.h"
 20: #endif
 21: #include "petscfix.h"

 23: /* 
 24:     For simplicity, we use a static size database
 25: */
 26: #define MAXOPTIONS 256
 27: #define MAXALIASES 25

 29: typedef struct {
 30:   int        N,argc,Naliases;
 31:   char       **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
 32:   char       *aliases1[MAXALIASES],*aliases2[MAXALIASES];
 33:   int        used[MAXOPTIONS];
 34:   PetscTruth namegiven;
 35:   char       programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
 36: } PetscOptionsTable;

 38: static PetscOptionsTable *options = 0;

 42: int PetscOptionsAtoi(const char name[],int *a)
 43: {
 44:   int        i,ierr,len;
 45:   PetscTruth decide,tdefault,mouse;

 48:   PetscStrlen(name,&len);
 49:   if (!len) SETERRQ(1,"character string of length zero has no numerical value");

 51:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 52:   if (!tdefault) {
 53:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 54:   }
 55:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 56:   if (!decide) {
 57:     PetscStrcasecmp(name,"DECIDE",&decide);
 58:   }
 59:   PetscStrcasecmp(name,"mouse",&mouse);

 61:   if (tdefault) {
 62:     *a = PETSC_DEFAULT;
 63:   } else if (decide) {
 64:     *a = PETSC_DECIDE;
 65:   } else if (mouse) {
 66:     *a = -1;
 67:   } else {
 68:     if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
 69:       SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
 70:     }
 71:     for (i=1; i<len; i++) {
 72:       if (name[i] < '0' || name[i] > '9') {
 73:         SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
 74:       }
 75:     }
 76:     *a  = atoi(name);
 77:   }
 78:   return(0);
 79: }

 83: int PetscOptionsAtod(const char name[],PetscReal *a)
 84: {
 85:   int        ierr,len;
 86:   PetscTruth decide,tdefault;

 89:   PetscStrlen(name,&len);
 90:   if (!len) SETERRQ(1,"character string of length zero has no numerical value");

 92:   PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
 93:   if (!tdefault) {
 94:     PetscStrcasecmp(name,"DEFAULT",&tdefault);
 95:   }
 96:   PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
 97:   if (!decide) {
 98:     PetscStrcasecmp(name,"DECIDE",&decide);
 99:   }

101:   if (tdefault) {
102:     *a = PETSC_DEFAULT;
103:   } else if (decide) {
104:     *a = PETSC_DECIDE;
105:   } else {
106:     if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
107:       SETERRQ1(1,"Input string %s has no numeric value ",name);
108:     }
109:     *a  = atof(name);
110:   }
111:   return(0);
112: }

116: /*@C
117:     PetscGetProgramName - Gets the name of the running program. 

119:     Not Collective

121:     Input Parameter:
122: .   len - length of the string name

124:     Output Parameter:
125: .   name - the name of the running program

127:    Level: advanced

129:     Notes:
130:     The name of the program is copied into the user-provided character
131:     array of length len.  On some machines the program name includes 
132:     its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
133: @*/
134: int PetscGetProgramName(char name[],int len)
135: {

139:   if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
140:   if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
141:   PetscStrncpy(name,options->programname,len);
142:   return(0);
143: }

147: int PetscSetProgramName(const char name[])
148: {

152:   options->namegiven = PETSC_TRUE;
153:   PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
154:   return(0);
155: }

159: /*@C
160:      PetscOptionsInsertString - Inserts options into the database from a string

162:      Not collective: but only processes that call this routine will set the options
163:                      included in the file

165:   Input Parameter:
166: .   in_str - string that contains options seperated by blanks


169:   Level: intermediate

171:   Contributed by Boyana Norris

173: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
174:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
175:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
176:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
177:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
178:           PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()

180: @*/
181: int PetscOptionsInsertString(const char in_str[])
182: {
183:   char       *str,*first,*second,*third,*final;
184:   int        len,ierr;
185:   PetscToken *token;

188:   PetscStrlen(in_str,&len);
189:   PetscMalloc(len,&str);
190:   PetscStrcpy(str, in_str);

192:   PetscTokenCreate(str,' ',&token);
193:   PetscTokenFind(token,&first);
194:   PetscTokenFind(token,&second);
195:   if (first && first[0] == '-') {
196:     if (second) {final = second;} else {final = first;}
197:     PetscStrlen(final,&len);
198:     while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
199:       len--; final[len] = 0;
200:     }
201:     PetscOptionsSetValue(first,second);
202:   } else if (first) {
203:     PetscTruth match;
204: 
205:     PetscStrcmp(first,"alias",&match);
206:     if (match) {
207:       PetscTokenFind(token,&third);
208:       if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
209:       PetscStrlen(third,&len);
210:       if (third[len-1] == 'n') third[len-1] = 0;
211:       PetscOptionsSetAlias(second,third);
212:     }
213:   }
214:   PetscTokenDestroy(token);
215:   PetscFree(str);
216: 
217:   return(0);
218: }

222: /*@C
223:      PetscOptionsInsertFile - Inserts options into the database from a file.

225:      Not collective: but only processes that call this routine will set the options
226:                      included in the file

228:   Input Parameter:
229: .   file - name of file


232:   Level: intermediate

234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
235:           PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
236:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
237:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
238:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
239:           PetscOptionsList(), PetscOptionsEList()

241: @*/
242: int PetscOptionsInsertFile(const char file[])
243: {
244:   char       string[128],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
245:   int        len,ierr,i,startIndex;
246:   FILE       *fd;
247:   PetscToken *token;

250:   PetscFixFilename(file,fname);
251:   fd   = fopen(fname,"r");
252:   if (fd) {
253:     while (fgets(string,128,fd)) {
254:       /* Comments are indicated by #, ! or % in the first column */
255:       if (string[0] == '#') continue;
256:       if (string[0] == '!') continue;
257:       if (string[0] == '%') continue;

259:       PetscStrlen(string,&len);

261:       /* replace tabs, ^M with " " */
262:       for (i=0; i<len; i++) {
263:         if (string[i] == '\t' || string[i] == '\r') {
264:           string[i] = ' ';
265:         }
266:       }
267:       for(startIndex = 0; startIndex < len-1; startIndex++) {
268:         if (string[startIndex] != ' ') break;
269:       }
270:       PetscTokenCreate(&string[startIndex],' ',&token);
271:       PetscTokenFind(token,&first);
272:       PetscTokenFind(token,&second);
273:       if (first && first[0] == '-') {
274:         if (second) {final = second;} else {final = first;}
275:         PetscStrlen(final,&len);
276:         while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
277:           len--; final[len] = 0;
278:         }
279:         PetscOptionsSetValue(first,second);
280:       } else if (first) {
281:         PetscTruth match;

283:         PetscStrcmp(first,"alias",&match);
284:         if (match) {
285:           PetscTokenFind(token,&third);
286:           if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
287:           PetscStrlen(third,&len);
288:           if (third[len-1] == '\n') third[len-1] = 0;
289:           PetscOptionsSetAlias(second,third);
290:         }
291:       }
292:       PetscTokenDestroy(token);
293:     }
294:     fclose(fd);
295:   }
296:   return(0);
297: }

301: /*@C
302:    PetscOptionsInsert - Inserts into the options database from the command line,
303:                    the environmental variable and a file.

305:    Input Parameters:
306: +  argc - count of number of command line arguments
307: .  args - the command line arguments
308: -  file - optional filename, defaults to ~username/.petscrc

310:    Note:
311:    Since PetscOptionsInsert() is automatically called by PetscInitialize(),
312:    the user does not typically need to call this routine. PetscOptionsInsert()
313:    can be called several times, adding additional entries into the database.

315:    Level: advanced

317:    Concepts: options database^adding

319: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
320: @*/
321: int PetscOptionsInsert(int *argc,char ***args,const char file[])
322: {
323:   int        ierr,rank;
324:   char       pfile[PETSC_MAX_PATH_LEN];
325:   PetscToken *token;

328:   MPI_Comm_rank(PETSC_COMM_WORLD,&rank);

330:   options->argc     = (argc) ? *argc : 0;
331:   options->args     = (args) ? *args : 0;

333:   if (file) {
334:     PetscOptionsInsertFile(file);
335:   } else {
336:     PetscGetHomeDirectory(pfile,240);
337:     PetscStrcat(pfile,"/.petscrc");
338:     PetscOptionsInsertFile(pfile);
339:   }

341:   /* insert environmental options */
342:   {
343:     char *eoptions = 0,*second,*first;
344:     int  len=0;
345:     if (!rank) {
346:       eoptions = (char*)getenv("PETSC_OPTIONS");
347:       PetscStrlen(eoptions,&len);
348:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
349:     } else {
350:       MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
351:       if (len) {
352:         PetscMalloc((len+1)*sizeof(char*),&eoptions);
353:       }
354:     }
355:     if (len) {
356:       MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
357:       eoptions[len] = 0;
358:        PetscTokenCreate(eoptions,' ',&token);
359:        PetscTokenFind(token,&first);
360:       while (first) {
361:         if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
362:         PetscTokenFind(token,&second);
363:         if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
364:           PetscOptionsSetValue(first,(char *)0);
365:           first = second;
366:         } else {
367:           PetscOptionsSetValue(first,second);
368:           PetscTokenFind(token,&first);
369:         }
370:       }
371:        PetscTokenDestroy(token);
372:       if (rank) {PetscFree(eoptions);}
373:     }
374:   }

376:   /* insert command line options */
377:   if (argc && args && *argc) {
378:     int        left    = *argc - 1;
379:     char       **eargs = *args + 1;
380:     PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;

382:     while (left) {
383:       PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
384:       PetscStrcmp(eargs[0],"-p4pg",&isp4);
385:       PetscStrcmp(eargs[0],"-p4yourname",&isp4yourname);
386:       PetscStrcmp(eargs[0],"-p4rmrank",&isp4rmrank);
387:       PetscStrcmp(eargs[0],"-p4wd",&tisp4);
388:       isp4 = (PetscTruth) (isp4 || tisp4);
389:       PetscStrcmp(eargs[0],"-np",&tisp4);
390:       isp4 = (PetscTruth) (isp4 || tisp4);
391:       PetscStrcmp(eargs[0],"-p4amslave",&tisp4);

393:       if (eargs[0][0] != '-') {
394:         eargs++; left--;
395:       } else if (isoptions_file) {
396:         PetscOptionsInsertFile(eargs[1]);
397:         eargs += 2; left -= 2;

399:       /*
400:          These are "bad" options that MPICH, etc put on the command line
401:          we strip them out here.
402:       */
403:       } else if (tisp4 || isp4rmrank) {
404:         eargs += 1; left -= 1;
405:       } else if (isp4 || isp4yourname) {
406:         eargs += 2; left -= 2;
407:       } else if ((left < 2) || ((eargs[1][0] == '-') &&
408:                ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
409:         PetscOptionsSetValue(eargs[0],PETSC_NULL);
410:         eargs++; left--;
411:       } else {
412:         PetscOptionsSetValue(eargs[0],eargs[1]);
413:         eargs += 2; left -= 2;
414:       }
415:     }
416:   }
417:   return(0);
418: }

422: /*@C
423:    PetscOptionsPrint - Prints the options that have been loaded. This is
424:    useful for debugging purposes.

426:    Collective on PETSC_COMM_WORLD

428:    Input Parameter:
429: .  FILE fd - location to print options (usually stdout or stderr)

431:    Options Database Key:
432: .  -optionstable - Activates PetscOptionsPrint() within PetscFinalize()

434:    Level: advanced

436:    Concepts: options database^printing

438: .seealso: PetscOptionsAllUsed()
439: @*/
440: int PetscOptionsPrint(FILE *fd)
441: {
442:   int i,ierr;

445:   if (!fd) fd = stdout;
446:   if (!options) {PetscOptionsInsert(0,0,0);}
447:   for (i=0; i<options->N; i++) {
448:     if (options->values[i]) {
449:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
450:     } else {
451:       PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
452:     }
453:   }
454:   return(0);
455: }

459: /*@C
460:    PetscOptionsGetAll - Lists all the options the program was run with in a single string.

462:    Not Collective

464:    Output Parameter:
465: .  copts - pointer where string pointer is stored

467:    Level: advanced

469:    Concepts: options database^listing

471: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
472: @*/
473: int PetscOptionsGetAll(char *copts[])
474: {
475:   int  i,ierr,len = 1,lent;
476:   char *coptions;

479:   if (!options) {PetscOptionsInsert(0,0,0);}

481:   /* count the length of the required string */
482:   for (i=0; i<options->N; i++) {
483:     PetscStrlen(options->names[i],&lent);
484:     len += 2 + lent;
485:     if (options->values[i]) {
486:       PetscStrlen(options->values[i],&lent);
487:       len += 1 + lent;
488:     }
489:   }
490:   PetscMalloc(len*sizeof(char),&coptions);
491:   coptions[0] = 0;
492:   for (i=0; i<options->N; i++) {
493:     PetscStrcat(coptions,"-");
494:     PetscStrcat(coptions,options->names[i]);
495:     PetscStrcat(coptions," ");
496:     if (options->values[i]) {
497:       PetscStrcat(coptions,options->values[i]);
498:       PetscStrcat(coptions," ");
499:     }
500:   }
501:   *copts = coptions;
502:   return(0);
503: }

507: /*@C
508:     PetscOptionsDestroy - Destroys the option database. 

510:     Note:
511:     Since PetscOptionsDestroy() is called by PetscFinalize(), the user 
512:     typically does not need to call this routine.

514:    Level: developer

516: .seealso: PetscOptionsInsert()
517: @*/
518: int PetscOptionsDestroy(void)
519: {
520:   int i;

523:   if (!options) return(0);
524:   for (i=0; i<options->N; i++) {
525:     if (options->names[i]) free(options->names[i]);
526:     if (options->values[i]) free(options->values[i]);
527:   }
528:   for (i=0; i<options->Naliases; i++) {
529:     free(options->aliases1[i]);
530:     free(options->aliases2[i]);
531:   }
532:   free(options);
533:   options = 0;
534:   return(0);
535: }

539: /*@C
540:    PetscOptionsSetValue - Sets an option name-value pair in the options 
541:    database, overriding whatever is already present.

543:    Not collective, but setting values on certain processors could cause problems
544:    for parallel objects looking for options.

546:    Input Parameters:
547: +  name - name of option, this SHOULD have the - prepended
548: -  value - the option value (not used for all options)

550:    Level: intermediate

552:    Note:
553:    Only some options have values associated with them, such as
554:    -ksp_rtol tol.  Other options stand alone, such as -ksp_monitor.

556:   Concepts: options database^adding option

558: .seealso: PetscOptionsInsert()
559: @*/
560: int PetscOptionsSetValue(const char iname[],const char value[])
561: {
562:   int        len,N,n,i,ierr;
563:   char       **names;
564:   const char *name = (char*)iname;
565:   PetscTruth gt,match;

568:   if (!options) {PetscOptionsInsert(0,0,0);}

570:   /* this is so that -h and -help are equivalent (p4 does not like -help)*/
571:   PetscStrcmp(name,"-h",&match);
572:   if (match) name = "-help";

574:   name++;
575:   /* first check against aliases */
576:   N = options->Naliases;
577:   for (i=0; i<N; i++) {
578:     PetscStrcmp(options->aliases1[i],name,&match);
579:     if (match) {
580:       name = options->aliases2[i];
581:       break;
582:     }
583:   }

585:   N     = options->N;
586:   n     = N;
587:   names = options->names;
588: 
589:   for (i=0; i<N; i++) {
590:     PetscStrcmp(names[i],name,&match);
591:     PetscStrgrt(names[i],name,&gt);
592:     if (match) {
593:       if (options->values[i]) free(options->values[i]);
594:       PetscStrlen(value,&len);
595:       if (len) {
596:         options->values[i] = (char*)malloc((len+1)*sizeof(char));
597:         PetscStrcpy(options->values[i],value);
598:       } else { options->values[i] = 0;}
599:       return(0);
600:     } else if (gt) {
601:       n = i;
602:       break;
603:     }
604:   }
605:   if (N >= MAXOPTIONS) {
606:     SETERRQ1(1,"No more room in option table, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
607:   }
608:   /* shift remaining values down 1 */
609:   for (i=N; i>n; i--) {
610:     names[i]           = names[i-1];
611:     options->values[i] = options->values[i-1];
612:     options->used[i]   = options->used[i-1];
613:   }
614:   /* insert new name and value */
615:   PetscStrlen(name,&len);
616:   names[n] = (char*)malloc((len+1)*sizeof(char));
617:   PetscStrcpy(names[n],name);
618:   if (value) {
619:     PetscStrlen(value,&len);
620:     options->values[n] = (char*)malloc((len+1)*sizeof(char));
621:     PetscStrcpy(options->values[n],value);
622:   } else {options->values[n] = 0;}
623:   options->used[n] = 0;
624:   options->N++;
625:   return(0);
626: }

630: /*@C
631:    PetscOptionsClearValue - Clears an option name-value pair in the options 
632:    database, overriding whatever is already present.

634:    Not Collective, but setting values on certain processors could cause problems
635:    for parallel objects looking for options.

637:    Input Parameter:
638: .  name - name of option, this SHOULD have the - prepended

640:    Level: intermediate

642:    Concepts: options database^removing option
643: .seealso: PetscOptionsInsert()
644: @*/
645: int PetscOptionsClearValue(const char iname[])
646: {
647:   int        N,n,i,ierr;
648:   char       **names,*name=(char*)iname;
649:   PetscTruth gt,match;

652:   if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
653:   if (!options) {PetscOptionsInsert(0,0,0);}

655:   name++;

657:   N     = options->N; n = 0;
658:   names = options->names;
659: 
660:   for (i=0; i<N; i++) {
661:     PetscStrcmp(names[i],name,&match);
662:     PetscStrgrt(names[i],name,&gt);
663:     if (match) {
664:       if (options->values[i]) free(options->values[i]);
665:       break;
666:     } else if (gt) {
667:       return(0); /* it was not listed */
668:     }
669:     n++;
670:   }
671:   if (n == N) return(0); /* it was not listed */

673:   /* shift remaining values down 1 */
674:   for (i=n; i<N-1; i++) {
675:     names[i]           = names[i+1];
676:     options->values[i] = options->values[i+1];
677:     options->used[i]   = options->used[i+1];
678:   }
679:   options->N--;
680:   return(0);
681: }

685: /*@C
686:    PetscOptionsReject - Generates an error if a certain option is given.

688:    Not Collective, but setting values on certain processors could cause problems
689:    for parallel objects looking for options.

691:    Input Parameters:
692: +  name - the option one is seeking 
693: -  mess - error message (may be PETSC_NULL)

695:    Level: advanced

697:    Concepts: options database^rejecting option

699: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
700:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
701:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
702:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
703:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
704:           PetscOptionsList(), PetscOptionsEList()
705: @*/
706: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
707: {
708:   int  ierr,len,n = options->Naliases;
709:   char *newname = (char *)inewname,*oldname = (char*)ioldname;

712:   if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
713:   if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
714:   if (n >= MAXALIASES) {
715:     SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n  src/sys/src/objects/options.c with larger value for MAXALIASES",MAXALIASES);
716:   }

718:   newname++; oldname++;
719:   PetscStrlen(newname,&len);
720:   options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
721:   PetscStrcpy(options->aliases1[n],newname);
722:   PetscStrlen(oldname,&len);
723:   options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
724:   PetscStrcpy(options->aliases2[n],oldname);
725:   options->Naliases++;
726:   return(0);
727: }

731: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
732: {
733:   int        i,N,ierr,len;
734:   char       **names,tmp[256];
735:   PetscTruth match;

738:   if (!options) {PetscOptionsInsert(0,0,0);}
739:   N = options->N;
740:   names = options->names;

742:   if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);

744:   /* append prefix to name */
745:   if (pre) {
746:     PetscStrncpy(tmp,pre,256);
747:     PetscStrlen(tmp,&len);
748:     PetscStrncat(tmp,name+1,256-len-1);
749:   } else {
750:     PetscStrncpy(tmp,name+1,256);
751:   }

753:   /* slow search */
754:   *flg = PETSC_FALSE;
755:   for (i=0; i<N; i++) {
756:     PetscStrcmp(names[i],tmp,&match);
757:     if (match) {
758:        *value = options->values[i];
759:        options->used[i]++;
760:        *flg = PETSC_TRUE;
761:        break;
762:      }
763:   }
764:   return(0);
765: }

769: /*@C
770:    PetscOptionsReject - Generates an error if a certain option is given.

772:    Not Collective, but setting values on certain processors could cause problems
773:    for parallel objects looking for options.

775:    Input Parameters:
776: +  name - the option one is seeking 
777: -  mess - error message (may be PETSC_NULL)

779:    Level: advanced

781:    Concepts: options database^rejecting option

783: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
784:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
785:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
786:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
787:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
788:           PetscOptionsList(), PetscOptionsEList()
789: @*/
790: int PetscOptionsReject(const char name[],const char mess[])
791: {
792:   int        ierr;
793:   PetscTruth flag;

796:   PetscOptionsHasName(PETSC_NULL,name,&flag);
797:   if (flag) {
798:     if (mess) {
799:       SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
800:     } else {
801:       SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
802:     }
803:   }
804:   return(0);
805: }

809: /*@C
810:    PetscOptionsHasName - Determines whether a certain option is given in the database.

812:    Not Collective

814:    Input Parameters:
815: +  name - the option one is seeking 
816: -  pre - string to prepend to the name or PETSC_NULL

818:    Output Parameters:
819: .  flg - PETSC_TRUE if found else PETSC_FALSE.

821:    Level: beginner

823:    Concepts: options database^has option name

825: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
826:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
827:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
828:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
829:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
830:           PetscOptionsList(), PetscOptionsEList()
831: @*/
832: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
833: {
834:   char       *value;
835:   int        ierr;
836:   PetscTruth isfalse,flag;

839:   PetscOptionsFindPair_Private(pre,name,&value,&flag);

841:   /* remove if turned off */
842:   if (flag) {
843:     PetscStrcmp(value,"FALSE",&isfalse);
844:     if (isfalse) flag = PETSC_FALSE;
845:     PetscStrcmp(value,"NO",&isfalse);
846:     if (isfalse) flag = PETSC_FALSE;
847:     PetscStrcmp(value,"0",&isfalse);
848:     if (isfalse) flag = PETSC_FALSE;
849:     PetscStrcmp(value,"false",&isfalse);
850:     if (isfalse) flag = PETSC_FALSE;
851:     PetscStrcmp(value,"no",&isfalse);
852:   }
853:   if (flg) *flg = flag;

855:   return(0);
856: }

860: /*@C
861:    PetscOptionsGetInt - Gets the integer value for a particular option in the database.

863:    Not Collective

865:    Input Parameters:
866: +  pre - the string to prepend to the name or PETSC_NULL
867: -  name - the option one is seeking

869:    Output Parameter:
870: +  ivalue - the integer value to return
871: -  flg - PETSC_TRUE if found, else PETSC_FALSE

873:    Level: beginner

875:    Concepts: options database^has int

877: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
878:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
879:           PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
880:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
881:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
882:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
883:           PetscOptionsList(), PetscOptionsEList()
884: @*/
885: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
886: {
887:   char       *value;
888:   int        ierr;
889:   PetscTruth flag;

894:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
895:   if (flag) {
896:     if (!value) {if (flg) *flg = PETSC_FALSE;}
897:     else {
898:       if (flg) *flg = PETSC_TRUE;
899:       PetscOptionsAtoi(value,ivalue);
900:     }
901:   } else {
902:     if (flg) *flg = PETSC_FALSE;
903:   }
904:   return(0);
905: }

909: /*@C
910:    PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular 
911:             option in the database.

913:    Not Collective

915:    Input Parameters:
916: +  pre - the string to prepend to the name or PETSC_NULL
917: -  name - the option one is seeking

919:    Output Parameter:
920: +  ivalue - the logical value to return
921: -  flg - PETSC_TRUE  if found, else PETSC_FALSE

923:    Level: beginner

925:    Notes:
926:        TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
927:        FALSE, false, NO, no, and 0 all translate to PETSC_FALSE

929:    Concepts: options database^has logical

931: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
932:           PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsLogical(),
933:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
934:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
935:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
936:           PetscOptionsList(), PetscOptionsEList()
937: @*/
938: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
939: {
940:   char       *value;
941:   PetscTruth flag,istrue,isfalse;
942:   int        ierr;

947:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
948:   if (flag) {
949:     if (flg) *flg = PETSC_TRUE;
950:     if (!value) {
951:       *ivalue = PETSC_TRUE;
952:     } else {
953:       *ivalue = PETSC_TRUE;
954:       PetscStrcmp(value,"TRUE",&istrue);
955:       if (istrue) return(0);
956:       PetscStrcmp(value,"YES",&istrue);
957:       if (istrue) return(0);
958:       PetscStrcmp(value,"YES",&istrue);
959:       if (istrue) return(0);
960:       PetscStrcmp(value,"1",&istrue);
961:       if (istrue) return(0);
962:       PetscStrcmp(value,"true",&istrue);
963:       if (istrue) return(0);
964:       PetscStrcmp(value,"yes",&istrue);
965:       if (istrue) return(0);
966:       PetscStrcmp(value,"on",&istrue);
967:       if (istrue) return(0);

969:       *ivalue = PETSC_FALSE;
970:       PetscStrcmp(value,"FALSE",&isfalse);
971:       if (isfalse) return(0);
972:       PetscStrcmp(value,"NO",&isfalse);
973:       if (isfalse) return(0);
974:       PetscStrcmp(value,"0",&isfalse);
975:       if (isfalse) return(0);
976:       PetscStrcmp(value,"false",&isfalse);
977:       if (isfalse) return(0);
978:       PetscStrcmp(value,"no",&isfalse);
979:       if (isfalse) return(0);
980:       PetscStrcmp(value,"off",&isfalse);
981:       if (isfalse) return(0);

983:       SETERRQ1(1,"Unknown logical value: %s",value);
984:     }
985:   } else {
986:     if (flg) *flg = PETSC_FALSE;
987:   }
988:   return(0);
989: }

993: /*@C
994:    PetscOptionsGetReal - Gets the double precision value for a particular 
995:    option in the database.

997:    Not Collective

999:    Input Parameters:
1000: +  pre - string to prepend to each name or PETSC_NULL
1001: -  name - the option one is seeking

1003:    Output Parameter:
1004: +  dvalue - the double value to return
1005: -  flg - PETSC_TRUE if found, PETSC_FALSE if not found

1007:    Level: beginner

1009:    Concepts: options database^has double

1011: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1012:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
1013:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1014:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1015:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1016:           PetscOptionsList(), PetscOptionsEList()
1017: @*/
1018: int PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1019: {
1020:   char       *value;
1021:   int        ierr;
1022:   PetscTruth flag;

1027:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1028:   if (flag) {
1029:     if (!value) {if (flg) *flg = PETSC_FALSE;}
1030:     else        {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1031:   } else {
1032:     if (flg) *flg = PETSC_FALSE;
1033:   }
1034:   return(0);
1035: }

1039: /*@C
1040:    PetscOptionsGetScalar - Gets the scalar value for a particular 
1041:    option in the database.

1043:    Not Collective

1045:    Input Parameters:
1046: +  pre - string to prepend to each name or PETSC_NULL
1047: -  name - the option one is seeking

1049:    Output Parameter:
1050: +  dvalue - the double value to return
1051: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1053:    Level: beginner

1055:    Usage:
1056:    A complex number 2+3i can be specified as 2,3 at the command line.
1057:    or a number 2.0e-10 - 3.3e-20 i  can be specified as 2.0e-10,3.3e-20

1059:    Concepts: options database^has scalar

1061: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1062:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1063:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1064:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1065:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1066:           PetscOptionsList(), PetscOptionsEList()
1067: @*/
1068: int PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1069: {
1070:   char       *value;
1071:   PetscTruth flag;
1072:   int        ierr;

1077:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1078:   if (flag) {
1079:     if (!value) {
1080:       if (flg) *flg = PETSC_FALSE;
1081:     } else {
1082: #if !defined(PETSC_USE_COMPLEX)
1083:       PetscOptionsAtod(value,dvalue);
1084: #else
1085:       PetscReal  re=0.0,im=0.0;
1086:       PetscToken *token;
1087:       char       *tvalue = 0;

1089:       PetscTokenCreate(value,',',&token);
1090:       PetscTokenFind(token,&tvalue);
1091:       if (!tvalue) { SETERRQ(1,"unknown string specified\n"); }
1092:       PetscOptionsAtod(tvalue,&re);
1093:       PetscTokenFind(token,&tvalue);
1094:       if (!tvalue) { /* Unknown separator used. using only real value */
1095:         *dvalue = re;
1096:       } else {
1097:         PetscOptionsAtod(tvalue,&im);
1098:         *dvalue = re + PETSC_i*im;
1099:       }
1100:       PetscTokenDestroy(token);
1101: #endif
1102:       if (flg) *flg    = PETSC_TRUE;
1103:     }
1104:   } else { /* flag */
1105:     if (flg) *flg = PETSC_FALSE;
1106:   }
1107:   return(0);
1108: }

1112: /*@C
1113:    PetscOptionsGetRealArray - Gets an array of double precision values for a 
1114:    particular option in the database.  The values must be separated with 
1115:    commas with no intervening spaces.

1117:    Not Collective

1119:    Input Parameters:
1120: +  pre - string to prepend to each name or PETSC_NULL
1121: .  name - the option one is seeking
1122: -  nmax - maximum number of values to retrieve

1124:    Output Parameters:
1125: +  dvalue - the double value to return
1126: .  nmax - actual number of values retreived
1127: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1129:    Level: beginner

1131:    Concepts: options database^array of doubles

1133: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1134:            PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
1135:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1136:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1137:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1138:           PetscOptionsList(), PetscOptionsEList()
1139: @*/
1140: int PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],int *nmax,PetscTruth *flg)
1141: {
1142:   char       *value;
1143:   int        n = 0,ierr;
1144:   PetscTruth flag;
1145:   PetscToken *token;

1150:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1151:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1152:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1154:   if (flg) *flg = PETSC_TRUE;

1156:   PetscTokenCreate(value,',',&token);
1157:   PetscTokenFind(token,&value);
1158:   while (n < *nmax) {
1159:     if (!value) break;
1160:     PetscOptionsAtod(value,dvalue++);
1161:     PetscTokenFind(token,&value);
1162:     n++;
1163:   }
1164:   PetscTokenDestroy(token);
1165:   *nmax = n;
1166:   return(0);
1167: }

1171: /*@C
1172:    PetscOptionsGetIntArray - Gets an array of integer values for a particular 
1173:    option in the database.  The values must be separated with commas with 
1174:    no intervening spaces. 

1176:    Not Collective

1178:    Input Parameters:
1179: +  pre - string to prepend to each name or PETSC_NULL
1180: .  name - the option one is seeking
1181: -  nmax - maximum number of values to retrieve

1183:    Output Parameter:
1184: +  dvalue - the integer values to return
1185: .  nmax - actual number of values retreived
1186: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1188:    Level: beginner

1190:    Concepts: options database^array of ints

1192: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 
1193:            PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1194:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1195:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1196:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1197:           PetscOptionsList(), PetscOptionsEList()
1198: @*/
1199: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1200: {
1201:   char       *value;
1202:   int        n = 0,ierr;
1203:   PetscTruth flag;
1204:   PetscToken *token;

1209:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1210:   if (!flag)  {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1211:   if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}

1213:   if (flg) *flg = PETSC_TRUE;

1215:   PetscTokenCreate(value,',',&token);
1216:   PetscTokenFind(token,&value);
1217:   while (n < *nmax) {
1218:     if (!value) break;
1219:     PetscOptionsAtoi(value,dvalue);
1220:     dvalue++;
1221:     PetscTokenFind(token,&value);
1222:     n++;
1223:   }
1224:   PetscTokenDestroy(token);
1225:   *nmax = n;
1226:   return(0);
1227: }

1231: /*@C
1232:    PetscOptionsGetString - Gets the string value for a particular option in
1233:    the database.

1235:    Not Collective

1237:    Input Parameters:
1238: +  pre - string to prepend to name or PETSC_NULL
1239: .  name - the option one is seeking
1240: -  len - maximum string length

1242:    Output Parameters:
1243: +  string - location to copy string
1244: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1246:    Level: beginner

1248:    Fortran Note:
1249:    The Fortran interface is slightly different from the C/C++
1250:    interface (len is not used).  Sample usage in Fortran follows
1251: .vb
1252:       character *20 string
1253:       integer   flg, ierr
1254:       call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1255: .ve

1257:    Concepts: options database^string

1259: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1260:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1261:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1262:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1263:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1264:           PetscOptionsList(), PetscOptionsEList()
1265: @*/
1266: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1267: {
1268:   char       *value;
1269:   int        ierr;
1270:   PetscTruth flag;

1275:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1276:   if (!flag) {
1277:     if (flg) *flg = PETSC_FALSE;
1278:   } else {
1279:     if (flg) *flg = PETSC_TRUE;
1280:     if (value) {
1281:       PetscStrncpy(string,value,len);
1282:     } else {
1283:       PetscMemzero(string,len);
1284:     }
1285:   }
1286:   return(0);
1287: }

1291: /*@C
1292:    PetscOptionsGetStringArray - Gets an array of string values for a particular
1293:    option in the database. The values must be separated with commas with 
1294:    no intervening spaces. 

1296:    Not Collective

1298:    Input Parameters:
1299: +  pre - string to prepend to name or PETSC_NULL
1300: .  name - the option one is seeking
1301: -  nmax - maximum number of strings

1303:    Output Parameter:
1304: +  strings - location to copy strings
1305: -  flg - PETSC_TRUE if found, else PETSC_FALSE

1307:    Level: beginner

1309:    Notes: 
1310:    The user should pass in an array of pointers to char, to hold all the
1311:    strings returned by this function.

1313:    The user is responsible for deallocating the strings that are
1314:    returned. The Fortran interface for this routine is not supported.

1316:    Contributed by Matthew Knepley.

1318:    Concepts: options database^array of strings

1320: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),  
1321:            PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1322:           PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1323:           PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1324:           PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1325:           PetscOptionsList(), PetscOptionsEList()
1326: @*/
1327: int PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],int *nmax,PetscTruth *flg)
1328: {
1329:   char       *value;
1330:   int        len,n,ierr;
1331:   PetscTruth flag;
1332:   PetscToken *token;
1333: 
1337:   PetscOptionsFindPair_Private(pre,name,&value,&flag);
1338:   if (!flag)  {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1339:   if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1340:   if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1341:   if (flg) *flg = PETSC_TRUE;

1343:   PetscTokenCreate(value,',',&token);
1344:   PetscTokenFind(token,&value);
1345:   n = 0;
1346:   while (n < *nmax) {
1347:     if (!value) break;
1348:     PetscStrlen(value,&len);
1349:     PetscMalloc((len+1)*sizeof(char),&strings[n]);
1350:     PetscStrcpy(strings[n],value);
1351:     PetscTokenFind(token,&value);
1352:     n++;
1353:   }
1354:   PetscTokenDestroy(token);
1355:   *nmax = n;
1356:   return(0);
1357: }

1361: /*@C
1362:    PetscOptionsAllUsed - Returns a count of the number of options in the 
1363:    database that have never been selected.

1365:    Not Collective

1367:    Output Parameter:
1368: .   N - count of options not used

1370:    Level: advanced

1372: .seealso: PetscOptionsPrint()
1373: @*/
1374: int PetscOptionsAllUsed(int *N)
1375: {
1376:   int  i,n = 0;

1379:   for (i=0; i<options->N; i++) {
1380:     if (!options->used[i]) { n++; }
1381:   }
1382:   *N = n;
1383:   return(0);
1384: }

1388: /*@
1389:     PetscOptionsLeft - Prints to screen any options that were set and never used.

1391:   Not collective

1393:    Options Database Key:
1394: .  -options_left - Activates OptionsAllUsed() within PetscFinalize()

1396:   Level: advanced

1398: .seealso: PetscOptionsAllUsed()
1399: @*/
1400: int PetscOptionsLeft(void)
1401: {
1402:   int        i,ierr;

1405:   for (i=0; i<options->N; i++) {
1406:     if (!options->used[i]) {
1407:       if (options->values[i]) {
1408:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1409:       } else {
1410:         PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1411:       }
1412:     }
1413:   }
1414:   return(0);
1415: }

1417: /*
1418:     PetscOptionsCreate - Creates the empty options database.

1420: */
1423: int PetscOptionsCreate(void)
1424: {

1428:   options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1429:   PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1430:   options->namegiven = PETSC_FALSE;
1431:   options->N         = 0;
1432:   options->Naliases  = 0;
1433:   return(0);
1434: }