home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / rftp.zip / getopt.3r < prev    next >
Text File  |  1995-08-15  |  7KB  |  182 lines
  1.  
  2. getopt(3r)                                                           getopt(3r)
  3. ───────────────────────────────────────────────────────────────────────────────
  4.  
  5. NAME
  6.      getopt - parse options from REXX program command line
  7.  
  8. SYNOPSIS
  9.      ch = getopt( optstr )
  10.      .
  11.      .
  12.      getopt: procedure expose getopt.
  13.          parse arg optstr
  14.  
  15. DESCRIPTION
  16.      The getopt subroutine helps a REXX program interpret command line 
  17.      flags that are passed to it.  The getopt subroutine processes the 
  18.      getopt. stem variable, which must have been prepared by the 
  19.      init_getopt subroutine.  The optstr parameter is a string of 
  20.      recognized flag letters.  If a letter is followed by a : (colon), the 
  21.      flag takes an argument.
  22.      
  23.      getopt.!optind indexes the next element of the getopt. stem variable 
  24.      to be processed. It is initialized to 1 (one) and the getopt 
  25.      subroutine updates it after calling each element of the getopt. 
  26.      parameter.
  27.      
  28.      The getopt subroutine returns the next flag letter in the getopt. stem 
  29.      variable that matches a letter in the optstr parameter.  If the flag 
  30.      takes an argument, the getopt subroutine sets getopt.!optarg to the 
  31.      argument as follows:
  32.      
  33.      *   If the flag was the last letter in the string pointed to by an
  34.      element of the getopt. stem variable, getopt.!optarg contains the next 
  35.      element of the getopt. stem variable and getopt.!optind is incremented 
  36.      by 2 (two).  If the resulting value of getopt.!optind is not less than 
  37.      getopt.0, this indicates a missing flag argument, and the getopt 
  38.      subroutine returns an error message.
  39.      
  40.      *   Otherwise, getopt.!optarg points to the string following the flag 
  41.      letter in that element of the getopt. stem variable and getopt.!optind 
  42.      is incremented by 1 (one).
  43.  
  44. PARAMETERS
  45.      optstr  Specifies a string of recognized flag letters. If a letter is 
  46.              followed by a : (colon), the flag is expected to take a 
  47.              parameter that may or may not be separated from it by white 
  48.              space.
  49.  
  50. GLOBAL VARIABLES
  51.      getopt uses a stem variable named getopt., which contains the 
  52.      following stems:
  53.  
  54.      getopt.0
  55.           Specifies the number of parameters passed to the program.
  56.  
  57.      getopt.1 through getopt.n
  58.           Specifies the list of parameters passed to the program.
  59.  
  60.      getopt.!errmsg
  61.           Contains the error message printed to the default output
  62.           stream when getopt encounters an error.  Useful if 
  63.           getopt.!opterr has been set to 0 (zero).
  64.  
  65.      getopt.!optarg
  66.           Stores the value of the option argument found by getopt.
  67.  
  68.      getopt.!opterr
  69.           If the application has not set this variable to 0 (zero), 
  70.           getopt prints diagnostic messages to the default output 
  71.           stream.  Initialized to 1 (zero) by init_getopt.
  72.  
  73.      getopt.!optind
  74.           Contains the index of the next argument to be processed.
  75.  
  76.      getopt.!optopt
  77.           When getopt detects an error and returns '?', getopt.!optopt 
  78.           contains the option character that caused the error.
  79.  
  80.      getopt.!program
  81.           Contains the name of the REXX program.  Initialized by 
  82.           init_getopt.
  83.  
  84.      getopt.!sp
  85.           Used internally by getopt.  Initialized by init_getopt.
  86.  
  87.      To avoid problems, do not use variables named !optarg, !opterr, 
  88.      !optind, !optopt, !program, or !sp in your program.
  89.  
  90. RETURN VALUES
  91.      The getopt subroutine returns the next flag letter specified on the 
  92.      command line.  A value of -1 (negative one) is returned when all 
  93.      command line flags have been parsed.  When the value of the 
  94.      getopt.!optind parameter is NULL, is not the - (minus) character, or 
  95.      is the "-" (minus) string, the getopt subroutine returns a value of 
  96.      -1 (negative one) without changing the value.  If the value of the 
  97.      getopt.!optind parameter is the "--" (dash) string, the getopt 
  98.      subroutine returns a value of -1 (negative one) after incrementing 
  99.      the value of the getopt.!optind parameter.
  100.  
  101. ERROR CODES
  102.      If the getopt subroutine encounters an option character that is not 
  103.      contained in optstr, a ? (question mark) character is returned.  If it 
  104.      detects a missing option argument, it returns a ? (question mark).  In 
  105.      either case, the getopt subroutine sets the getopt.!optopt variable to 
  106.      the option character that caused the error. If the application has not 
  107.      set the variable getopt.!opterr to 0 (zero), the getopt subroutine 
  108.      also prints a diagnostic message to the default output stream.
  109.  
  110. EXAMPLE
  111.      The following code fragment processes the flags for a command that can 
  112.      take the mutually exclusive flags a and b, and the flags f and o, both 
  113.      of which require parameters.
  114.  
  115.      /*  */
  116.      
  117.      parse arg argv
  118.      call init_getopt argv
  119.  
  120.      aflg = 0
  121.      eflg = 0
  122.      errflg = 0
  123.  
  124.      optstr = "abf:o:"
  125.      c = getopt(optstr)
  126.      do while c \= -1
  127.          select
  128.              when c = 'a' then
  129.                  if bflg \= 0 then
  130.                      errflg = errflg + 1
  131.                  else
  132.                      aflg = aflg + 1
  133.              when c = 'b' then
  134.                  if aflg \= 0 then
  135.                      errflg = errflg + 1
  136.                  else
  137.                      bflg = bflg + 1
  138.              when c = 'f' then
  139.                  ifile = getopt.!optarg
  140.              when c = 'o' then
  141.                  ofile = getopt.!optarg
  142.              when c = '?' then
  143.                  errflg = errflg + 1
  144.          end                         /* select */
  145.  
  146.          if errflg > 0 then do
  147.              say "usage: . . . "
  148.              exit 2
  149.          end
  150.  
  151.          c = getopt(optstr)
  152.      end                             /* do while */
  153.  
  154.      exit
  155.  
  156. NOTES
  157.      This getopt was patterned after the public domain version that is 
  158.      provided by the AT&T UNIX(tm) System Toolchest.
  159.  
  160. SEE ALSO
  161.      init_getopt(3r)
  162.  
  163. PROGRAM AUTHOR
  164.      Lawrence R. "Rod" Buchanan
  165.  
  166. COPYRIGHT
  167.      Copyright (c) 1994-95 Lawrence R Buchanan.  ALL RIGHTS RESERVED.
  168.  
  169.      This program is free software; you can redistribute it and/or modify
  170.      it under the terms of the GNU General Public License as published by
  171.      the Free Software Foundation; either version 2, or (at your option)
  172.      any later version.
  173.  
  174.      This program is distributed in the hope that it will be useful,
  175.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  176.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  177.      GNU General Public License for more details.
  178.  
  179.      You should have received a copy of the GNU General Public License
  180.      along with this program; if not, write to the Free Software
  181.      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  182.