COBOL API reference

Every public function of the kwker.cpy copybook for GnuCOBOL, which calls the C library directly, with its parameters and results (Kwker 0.1.0).

Kwker for COBOL (GnuCOBOL): order constants and the CALL conventions of the C library (libkwker_c). Tables are contiguous binary items of the key width, passed BY REFERENCE; counts BY VALUE as BINARY-DOUBLE UNSIGNED (C size_t); the order BY VALUE as BINARY-LONG UNSIGNED; RETURNING a BINARY-LONG (0: done, -1: invalid arguments). Compile with -fstatic-call (cobc) so CALL "literal" links to the C functions directly.

BINARY-LONG (S9(9) COMP-5)    "kwker_i32_sort_order"
BINARY-DOUBLE (S9(18) COMP-5) "kwker_i64_sort_order"
COMP-1 (float) / COMP-2 (double): "kwker_f32/f64_..."

CALL "kwker_i64_sort_order" USING BY REFERENCE the-table
     BY VALUE the-count BY VALUE KWKER-ORDER
     RETURNING the-rc
CALL "kwker_i64_select" USING BY REFERENCE the-table
     BY VALUE the-count BY VALUE k-zero-based
     BY VALUE KWKER-ORDER RETURNING the-rc

Alphanumeric (PIC X(w)) keys at byte offset off of each record:

CALL "kwker_argsort_fixed_strings_field" USING BY REFERENCE
     the-table BY VALUE the-count BY VALUE record-length
     BY VALUE off BY VALUE w BY VALUE KWKER-COLLATE-*
     BY REFERENCE indices RETURNING the-rc

(all BY VALUE sizes BINARY-DOUBLE UNSIGNED, the collation BINARY-LONG UNSIGNED; indices: BINARY-DOUBLE UNSIGNED OCCURS the-count, 0-based, the stable order: equal keys keep their sequence; byte order = the ASCII collating sequence - all keys share w, so the space padding compares alike) and move the records by that order in place:

CALL "kwker_permute_in_place" USING BY REFERENCE the-table
     BY VALUE the-count BY VALUE record-length
     BY REFERENCE indices RETURNING the-rc

Under a collating sequence (an ALPHABET clause, EBCDIC order for ASCII data): 256 byte weights, BINARY-CHAR UNSIGNED OCCURS 256 (weight of byte b at b + 1; equal weights compare equal), every byte of the key compared as COBOL compares PIC X fields:

CALL "kwker_argsort_fixed_strings_field_table" USING
     BY REFERENCE the-table BY VALUE the-count
     BY VALUE record-length BY VALUE off BY VALUE w
     BY REFERENCE weights BY REFERENCE indices
     RETURNING the-rc

the weights of an alphabet: the 256 byte values sorted by it (SORT ... COLLATING SEQUENCE IS alphabet), each weight its position minus 1 (sstestc.cob); or a built-in table:

CALL "kwker_collation_table" USING
     BY VALUE KWKER-TABLE-EBCDIC-037 BY REFERENCE weights
     RETURNING the-rc

KWKER-ASCENDING, KWKER-DESCENDING, KWKER-NANS-FIRST Page

78 KWKER-ASCENDING  VALUE 0.
78 KWKER-DESCENDING VALUE 1.
78 KWKER-NANS-FIRST VALUE 2.

The order argument of the sort and select calls: KWKER-ASCENDING or KWKER-DESCENDING, plus KWKER-NANS-FIRST to put NaNs first.

KWKER-COLLATE-BYTES, KWKER-COLLATE-CASELESS, KWKER-COLLATE-NATURAL, KWKER-COLLATE-NATURAL-CASELESS Page

78 KWKER-COLLATE-BYTES     VALUE 0.
78 KWKER-COLLATE-CASELESS  VALUE 1.
78 KWKER-COLLATE-NATURAL   VALUE 2.
78 KWKER-COLLATE-NATURAL-CASELESS VALUE 3.

The collation of kwker_argsort_fixed_strings_field: bytes, bytes ignoring ASCII case, natural (digit runs compared as numbers), or natural ignoring case.

KWKER-TABLE-BYTES, KWKER-TABLE-EBCDIC-037, KWKER-TABLE-FROM-EBCDIC-037 Page

78 KWKER-TABLE-BYTES         VALUE 0.
78 KWKER-TABLE-EBCDIC-037    VALUE 1.
78 KWKER-TABLE-FROM-EBCDIC-037 VALUE 2.

The built-in weight tables of kwker_collation_table: byte order, EBCDIC code page 037 order for Latin-1 / ASCII data, or Latin-1 order for EBCDIC 037 data.