Question

CBL_GC_GETOPT provides the quite well-known option parser, getopt, for GnuCOBOL. The usage of this system routine is described by the following example.

        identification division.
        program-id. prog.

        data division.
        working-storage section.
            78 shortoptions value "jkl".

            01 longoptions.
                05 optionrecord occurs 2 times.
                    10 optionname   pic x(25).
                    10 has-value    pic 9.
                    10 valpoint     pointer value NULL.
                    10 return-value pic x(4).

            01 longind     pic 99.
            01 long-only   pic 9 value 1.

            01 return-char pic x(4).
            01 opt-val     pic x(10).

            01 counter     pic 9 value 0.

We first need to define the necessary fields for getopt’s shortoptions (so), longoptions (lo), longoption index (longind), long-only-option (long-only) and also the fields for return values return-char and opt-val (arbitrary size with trimming, see return codes).

The shortoptions are written down as an alphanumeric field (i.e., a string with arbitrary size) as follows:

"ab:c::d"

This means we want getopt to look for shortoptions named a, b, c or d and we demand an option value for b and we are accepting an optional one for c.

The longoptions are defined as a table of records with oname, has-value, valpoint and val.

• oname defines the name of a longoption.
• has-value defines if an option value is demanded (has-val = 1), optional (has-val = 2) or not required (has-val = 0).
• valpoint is a pointer used to specify an address to save getopt’s return value to. The pointer is optional. If it is NULL, getopt returns a value as usual. If you use the pointer it has to point to a PIC X(4) field.
• The field val is a PIC X(4) character which is returned if the longoption was recognized.

The longoption structure is immutable! You can only vary the number of records.

Now we have the tools to run CBL_GC_GETOPT within the procedure division.

        procedure division.
            move "version" to optionname   (1).
            move 0         to has-value    (1).
            move "v"       to return-value (1).

            move "verbose" to optionname   (2).
            move 0         to has-value    (2).
            move "V"       to return-value (2).

            perform with test after until return-code = -1
                call 'CBL_GC_GETOPT' using
                   by reference shortoptions longoptions longind
                   by value long-only
                   by reference return-char opt-val
                end-call

                display return-char end-display
                display opt-val     end-display
            end-perform
            stop run.

The example shows how we initialize all parameters and call the routine until CBL_GC_GETOPT runs out of options and returns -1.

If the option is recognized, return-char contains the option character. Otherwise, return-char will contain one of the following:

?

undefined or ambiguous option

1

non-option (only if first byte of so is ‘-’)

0

valpoint != NULL and we are writing the return value to the specified address

-1

no more options (or reached the first non-option if first byte of so is ‘+’)

The return-code of CBL_GC_GETOPT is one of:

1

a non-option (only if first byte of so is ‘-’)

0

valpoint != NULL and we are writing the return value to the specified address

-1

no more options (or reach the first non-option if first byte of so is ‘+’)

2

truncated option value in opt-val (because opt-val was too small)

3

regular answer from getopt