home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / getopt.zip / getopt.3r < prev    next >
Text File  |  1994-04-20  |  6KB  |  156 lines
  1. GetOpt(3)                                                           GetOpt(3)
  2. ─────────────────────────────────────────────────────────────────────────────
  3.  
  4. NAME
  5.     GetOpt - parse options from REXX program command line
  6.  
  7. SYNTAX
  8.     ch = GetOpt( optstr )
  9.     .
  10.     .
  11.     GetOpt: procedure expose GetOpt.
  12.         parse arg optstr
  13.  
  14. DESCRIPTION
  15.     The GetOpt subroutine helps a REXX program interpret command-line flags 
  16.     that are passed to it.  The GetOpt subroutine processes the GetOpt. stem 
  17.     variable, which must have been prepared by the SetupArg subroutine prior 
  18.     to calling GetOpt.  The optstr parameter is a string of recognized flag 
  19.     letters.  If a letter is followed by a : (colon), the flag takes an 
  20.     argument.
  21.     
  22.     GetOpt._optind indexes the next element of the GetOpt. stem variable to 
  23.     be processed. It is initialized to 1 (one) and the GetOpt subroutine 
  24.     updates it after calling each element of the GetOpt. parameter.
  25.     
  26.     The GetOpt subroutine returns the next flag letter in the GetOpt. stem 
  27.     variable that matches a letter in the optstr parameter.  If the flag 
  28.     takes an argument, the GetOpt subroutine sets GetOpt._optarg to the 
  29.     argument as follows:
  30.     
  31.     *   If the flag was the last letter in the string pointed to by an
  32.     element of the GetOpt. stem variable, GetOpt._optarg contains the next 
  33.     element of the GetOpt. stem variable and GetOpt._optind is incremented by 2 
  34.     (two).  If the resulting value of GetOpt._optind is not less than 
  35.     GetOpt.0, this indicates a missing flag argument, and the GetOpt 
  36.     subroutine returns an error message.
  37.     
  38.     *   Otherwise, GetOpt._optarg points to the string following the flag 
  39.     letter in that element of the GetOpt. stem variable and GetOpt._optind 
  40.     is incremented by 1 (one).
  41.  
  42. PARAMETERS
  43.     optstr  Specifies a string of recognized flag letters. If a letter is 
  44.             followed by a : (colon), the flag is expected to take a parameter 
  45.             that may or may not be separated from it by white space.
  46.  
  47. GLOBAL VARIABLES
  48.     GetOpt uses a stem variable named GetOpt., which contains the following 
  49.     stems:
  50.  
  51.     GetOpt.0
  52.             Specifies the number of parameters passed to the routine.
  53.  
  54.     GetOpt.1 through GetOpt.n
  55.             Specifies the list of parameters passed to the routine.
  56.  
  57.     GetOpt._optarg
  58.             Stores the value of the option argument found by GetOpt.
  59.  
  60.     GetOpt._opterr
  61.             If application has not set this variable to 0 (zero), the GetOpt 
  62.             subroutine prints a diagnostic message to the default output 
  63.             stream.
  64.  
  65.     GetOpt._optind
  66.             Contains the index of the next argument to be processed.
  67.  
  68.     GetOpt._optopt
  69.             When GetOpt detects an error and returns '?', GetOpt._optopt 
  70.             contains the option character that caused the error.
  71.  
  72.     GetOpt._program
  73.             Contains the name of the REXX program.  Initialized by SetupArg.
  74.  
  75.     GetOpt._sp
  76.             Used internally by GetOpt.  Initialized by SetupArg.
  77.  
  78.     To avoid problems, do not use variables named _optarg, _opterr, _optind, 
  79.     _optopt, _program, or _sp in your program.
  80.  
  81. RETURN VALUES
  82.     The GetOpt subroutine returns the next flag letter specified on the 
  83.     command line.  A value of -1 (negative one) is returned when all command 
  84.     line flags have been parsed.  When the value of the GetOpt._optind 
  85.     parameter is NULL, is not the - (minus) character, or is the "-" (minus) 
  86.     string, the GetOpt subroutine returns a value of -1 (negative one) 
  87.     without changing the value.  If the value of the GetOpt._optind 
  88.     parameter is the "--" (dash) string, the GetOpt subroutine returns a 
  89.     value of -1 (negative one) after incrementing the value of the 
  90.     GetOpt._optind parameter.
  91.  
  92. ERROR CODES
  93.     If the GetOpt subroutine encounters an option character that is not 
  94.     contained in optstr, a ? (question mark) character is returned.  If it 
  95.     detects a missing option argument, it returns a ? (question mark).  In 
  96.     either case, the GetOpt subroutine sets the GetOpt._optopt variable to 
  97.     the option character that caused the error. If the application has not 
  98.     set the variable GetOpt._opterr to 0 (zero), the GetOpt subroutine also 
  99.     prints a diagnostic message to the default output stream.
  100.  
  101. EXAMPLE
  102.     The following code fragment processes the flags for a command that can 
  103.     take the mutually exclusive flags a and b, and the flags f and o, both 
  104.     of which require parameters.
  105.  
  106.     /*  */
  107.     
  108.     parse arg args
  109.     call SetupArg args
  110.     
  111.     aflg = 0
  112.     eflg = 0
  113.     errflg = 0
  114.     
  115.     optstr = "abf:o:"
  116.     c = GetOpt(optstr)
  117.     do while c \= -1
  118.         select
  119.             when c = 'a' then
  120.                 if bflg \= 0 then
  121.                     errflg = errflg + 1
  122.                 else
  123.                     aflg = aflg + 1
  124.             when c = 'b' then
  125.                 if aflg \= 0 then
  126.                     errflg = errflg + 1
  127.                 else
  128.                     bflg = bflg + 1
  129.             when c = 'f' then
  130.                 ifile = GetOpt._optarg
  131.             when c = 'o' then
  132.                 ofile = GetOpt._optarg
  133.             when c = '?' then
  134.                 errflg = errflg + 1
  135.         end                         /* select */
  136.     
  137.         if errflg > 0 then do
  138.             say "usage: . . . "
  139.             exit 2
  140.         end
  141.     
  142.         c = GetOpt(optstr)
  143.     end                             /* do while */
  144.  
  145.     exit
  146.  
  147. NOTES
  148.     This GetOpt was patterned after the public domain version that is 
  149.     provided by the AT&T UNIX(tm) System Toolchest.
  150.  
  151. SEE ALSO
  152.     SetupArg(3)
  153.  
  154. COPYRIGHT
  155.     Copyright (c) 1994 Lawrence R Buchanan.
  156.