1. ARITPK Floating point arithmetic
  2. BITPK Bit manipulation
  3. CALCPK Calculator functions
  4. CALRPK Calendar functions
  5. CERTPK Certify number functions
  6. COMPPK Compression function
  7. DATEPK Date encoding/checking
  8. GETNBR Convert text to number
  9. MATHPK Mathematical functions
  10. NAMEPK Name functions
  11. PWRDPK Password authentication
  12. STRNPK String functions
  13. Coding Style

Portable Packages

The packages are from the ETK tool set. See http://www.etk.com The stuff was written by Pieter Hintjens and Leif Svalgaard. E-mail to leif@etk.com for help.

With one exception (COMPPK) the code is completely portable and will run on all systems with all compilers. There are a few compilers which do not support FILLER as a group name. You can either rename the few group names you come across, or ask Leif to send you a program to do this automatically.

The value of TASK-ID PIC X(4) is immaterial unless you are using ETK. Just leave it alone.

ARITPK

Source code

Summary: Provides primarily the four standard arithmetic operations on floating-point numbers with 18-digit accuracy as well as conversions to/from portable floating point formats. An accurate power operation complements the basic operations.

How to use: Provide the operands as a signed mantissa and a signed exponent. The package returns the result in the same format. For conversions, place the operand in the result parameters.

Limitations: The division and the power operations are in some cases only accurate to 17 digits. The operations are truncating instead of rounding.

COBOL does not support floating point arithmetic in a portable manner. For low-precision work, you can get far by dividing the 18-digit numeric range into a 9-digit whole part and a 9-digit fraction, ie. by using the picture S9(9)V9(9). For more decimals or larger numbers this will not do. The ARITPK package was written to provide a means for such high-precision work.

To call ARITPK, define ARITPK-CONTROL as follows:

            01  ARITPK-CONTROL.
                02  ARITPK-TASK-ID              PIC X(4).
                02  ARITPK OPERATION            PIC X..
                02  ARITPK FEEDBACK             PIC X.
                    88  ARITPK-NO-ERRORS               VALUE IS SPACE.
                    88  ARITPK-RANGE-ERROR             VALUE IS "R".
                    88  ARITPK-INVALID-OPERATION       VALUE IS "O".

                02  ARITPK-FLOAT-OPERAND-1
                    03  ARITPK-MANTISSA-1       PIC SV9(18).
                    03  ARITPK-EXPONENT-1       PIC  S9(02).

                02  ARITPK-FLOAT-OPERAND-2
                    03  ARITPK-MANTISSA-2       PIC SV9(18).
                    03  ARITPK-EXPONENT-2       PIC  S9(02).

                02  ARITPK-FLOAT-RESULT
                    03  ARITPK-MANTISSA-3       PIC SV9(18).
                    03  ARITPK-EXPONENT-3       PIC  S9(02).

                02  ARITPK-FIXED-LONG.
                    03  ARITPK-LONG-WHOLE       PIC  9(18).
                    03  ARITPK-LONG-DECS        PIC V9(18).
                    03  ARITPK-LONG-SIGN        PIC  X(01).

                02  ARITPK-FIXED-SHORT          PIC S9(9)V9(9)  COMP.
Define CALL-ARITPK as follows:
            CALL-ARITPK.
                CALL "ARITPK"
                    USING ARITPK-CONTROL
                .
ARITPK primarily supports the four basic aritmetic operations on floating-point numbers, as well as various conversions. Operands are given in a portable floating- point format as a signed mantissa and a signed exponent. The result is returned as a normalized floating-point number in the same format.

Floating point numbers are expressed in radix 10 as value = mantissa * 10exp, with the absolute value of the mantissa being either zero or normalized to the closed interval [0.1:0.999...].

The long fixed-point number is given with a separate sign, which must be one of the characters "+" or "-" or space, which is treated as "+". A short fixed-point format is provided as a signed computational number.

Although the mantissas are declared as having the virtual point at the left-hand end (PIC SV9(18)), you may just as well declare them to have the point at the right-hand end (PIC S9(18)). This may make it easier for you to manipulate the numbers. The only thing that matters is the actual digits.

Floating-point exponents greater than 80 are classified as range errors and return the "R" feedback. Range errors also result, when the arguments for the power operation are invalid. Exponents smaller than -80 cause the result to be set to zero. A zero result has a mantissa of zero (with exponent zero).

ARITPK supports these operations:

ARITPK returns these feedbacks: a space means there were no errors; an "R" (range error) means a numeric result of a division or multiplication was out of range (division by zero or the result being numerically larger than 1080); an "O" means that the specified operation was invalid.

BITPK

Source code

Summary: Provides bit manipulations of up to 32 bits. Can get, set, clear, test, and pack bits.

How to use: Instead of non-portable redefinitions to access bits packed in numeric variables, use BITPK's get operation to convert a number into a string of 32 characters each with values "0" or "1". You can then easily test or otherwise manipulate these character values. The pack operation packs the character values back into a number.

Limitations: At most 32 bits can be handled at a time.

To call BITPK, define BITPK-CONTROL as follows:

              01  BITPK-CONTROL.
                  02  BITPK-TASK-ID           PIC X(4) .
                  02  BITPK-OPERATION         PIC X(1) .
                  02  BITPK-FEEDBACK          PIC X(1) .
                  02  BITPK-NUMBER            PIC 9(10).
                  02  BITPK-BITS.
                      03  BITPK-BIT           PIC X(1)  OCCURS 32 TIMES.
Define CALL-BITPK as follows:
              CALL-BITPK.
                  CALL "BITPK"
                        USING BITPK-CONTROL
              .
BITPK supports the following operations: BITPK returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid. An "R" means that the number given was too large. An "A", "N", or "S" means that either All, None, or Some bits met the condition.

CALCPK

Source code

Summary: Computes the value of an expression. The expression can contain decimal numbers, arithmetic operators, mathematical functions, parentheses, and user-defined variables.

How to use: You give CALCPK a mathematical expression, composed of numbers, operators, and mathematical functions. CALCPK computes the result of the expression.

Limitations: All numbers are stored as fixed- decimal, 18-digit signed values; larger or smaller numbers are not possible. Up to 5 variables can be used in the expression. The `**' operator is implemented using logarithms so its argument must be greater than zero.

To call CALCPK, define CALCPK-CONTROL as follows:

            01  CALCPK-CONTROL.
                02  CALCPK-TASK-ID          PIC X(4).
                02  CALCPK-OPERATION        PIC X      VALUE "C".
                02  CALCPK-FEEDBACK         PIC X.
                02  CALCPK-POINT-CHAR       PIC X      VALUE ".".
                02  CALCPK-ERROR-CODE       PIC X(2).
                02  CALCPK-ERROR-TEXT       PIC X(30).
                02  CALCPK-ERROR-POSN       PIC 9(2).
                02  CALCPK-EXPRESSION       PIC X(80).
                02  CALCPK-RESULT           PIC S9(9)V9(9).
                02  CALCPK-VARIABLE         PIC S9(9)V9(9) OCCURS 5 TIMES.
Define CALL-CALCPK as follows:
             CALL-CALCPK.
                 CALL "CALCPK"
                     USING CALCPK-CONTROL
                 .
CALCPK supports one operation - "C" (compute). Before you call CALCPK, set the operation code to "C" and the point character to "." or "," as desired. Initialize the variables to their desired values (for example, the results of previous expressions), or to zero.

CALCPK returns these feedbacks: a space means there were no errors; an "F" (full) means that there was some overflow error; an "S" (syntax) means that the expression contained a syntax error. An "O" means that the specified operation was invalid.

For overflow and syntax errors, CALCPK returns both a short error code (2 letters) and a longer English error text. It also returns the position within the expression (starting at 1) where the error occurred. The calling program can display the error text directly, or use the error code to retrieve a message from a user-defined message file.

The error codes possible after an overflow error are:

The error codes possible after a syntax error are:

An expression is a line of instructions that returns a numeric value. An expression may contain operands (numbers or variable), operators (eg. +, -), functions (eg. SIN, COS), and parentheses. Expressions can be as simple or complex as desired, so long as they can fit into one line. A function acts on a single value or an expression enclosed in parentheses; the function name comes before the value or expression, eg. `SIN(1-A)'; and tokens may be separated by spaces if desired. The five variables are named A through E. The value of the previous result is also a variable with name R.

The valid operators are: !, &, <, >, =, <=, >=, <>, -, +, /, *, and ** (`or', `and', `less than', `greater than', `equal', `less or equal', `greater or equal', `not equal', `minus', `plus', `divided by', `times', and `to the power of' respectively). `!' has the lowest priority, then `&', then comparisons, then `-' and `+', then `*' and `/', and then `**' and unary signs and functions, which have the highest priority.

The result of a comparison or a logical operator (eg. `A > 0') is 1 if true and 0 if false.

The default priorities of operators may be changed by using parentheses to group part of an expression together; that part will be executed before the rest of the expression. For example, `A+100*2' evaluates as `A plus 200' while `(A+100)*2' evaluates as `A plus 100, times 2'. Parentheses may be nested to any reasonable degree, in which case the innermost groupings are executed first. The number of left and right parentheses used in an expression must be the same.

CALCPK supports these functions:

CALRPK

Source code

Summary: Converts dates between various formats (Gregorian, Julian, Lillian), and computes the day of the week, and week of the year.

How to use: CALRPK defines three date formats; Gregorian (YYYYMMDD), Julian (YYYYDDD), and Lillian (DDDDDDD) which is days since the start of the Gregorian calendar: 15 Oct. 1582. You can convert dates between these formats, for example, to compute the date 100 days from today. CALRPK also returns the day of the week or the week of the year for a date in any of these formats. Some Cobol systems operate with an integer-of-date that is the number of days since Dec. 31, 1600. To convert to Lillian days add 6653 to integer-of-date.

Limitations: Dates must not be earlier than 1 Jan 1600. The algorithm used to compute the week of the year is simplified from the normal standards which allow week 53 to cover the first partial week of a year.

To call CALRPK, define CALRPK-CONTROL as follows:

            01  CALRPK-CONTROL.
                02  CALRPK-TASK-ID          PIC X(4).
                02  CALRPK-OPERATION        PIC X(2).
                02  CALRPK-FEEDBACK         PIC X.
                02  CALRPK-GREGORIAN-DATE   PIC 9(8).
                02  CALRPK-JULIAN-FORMAT    PIC 9(7).
                02  FILLER                  REDEFINES  CALRPK-JULIAN-FORMAT.
                    03  CALRPK-JULIAN-YYYY  PIC 9(4).
                    03  CALRPK-JULIAN-DDD   PIC 9(3).
                02  CALRPK-LILLIAN-DAYS     PIC 9(7).
                02  CALRPK-DAY-OF-WEEK      PIC 9.
                02  CALRPK-WEEK-OF-YEAR     PIC 9(2).
Define CALL-CALRPK as follows:
            CALL-CALRPK.
                CALL "CALRPK"
                    USING CALRPK-CONTROL
                .
CALRPK accepts a 2-character operation code. The first character, "G", "J", or "L" indicates which date format the calling program is supplying. The second character may be one of the following: CALRPK returns these feedbacks: a space means there were no errors; an "E" means that the date supplied was invalid. All operations check that the supplied date is valid. An "O" means that the specified operation was invalid.

CERTPK

Source code

Summary: Converts a number or date into full text in a number of European languages, including English, French, German, Spanish, Italian, and Roman numerals.

How to use: You supply an integer number or date, and a language code. CERTPK returns a fully-verbalized, or shortened, text. CERTPK will replace national characters by portable characters if desired. CERTPK is intended for use by programs that print invoices, checks, etc.

Limitations: Only Roman alphabets with slight variations (ie. twelve European languages) and Latin numerals are supported. The maximum returned text is 120 characters. The largest number that can be certified is 999,999,999. The largest Roman numeral is 4,999 (their limitation, not ours).

To call CERTPK, define CERTPK-CONTROL and CERTPK-DATA as follows:

            01  CERTPK-CONTROL.
                02  CERTPK-TASK-ID          PIC X(4).
                02  CERTPK-OPERATION        PIC X.
                02  CERTPK-MODE             PIC X.
                02  CERTPK-FEEDBACK         PIC X.
                02  CERTPK-LANGUAGE         PIC X(2).
                02  CERTPK-SIZE             PIC S9(3)  COMP.
                02  CERTPK-NUMBER           PIC 9(9).
                02  FILLER                  REDEFINES  CERTPK-NUMBER.
                    03  FILLER              PIC X.
                    03  CERTPK-DATE         PIC 9(8).
                02  CERTPK-DIGITS           PIC 9.

            01  CERTPK-DATA.
                02  FILLER                  PIC X(120).
Define CALL-CERTPK as follows:
            CALL-CERTPK.
                CALL "CERTPK"
                    USING CERTPK-CONTROL
                          CERTPK-DATA
                 .
CERTPK supports these operations: CERTPK returns these feedbacks: a space means there were no errors; an "L" (language) means that the language code was invalid; an "S" (size) means that the number was too large - this only happens if you are using Roman numerals, where the limit is 4999; a "D" means that the date was invalid - either the day, month, or year was invalid. An "O" means that the specified operation was invalid.

Before calling CERTPK you should also specify the CERTPK- MODE, -LANGUAGE, and -SIZE. The mode may be "N" (national) or "P" (portable) and determines whether or not national characters are converted into standard English letters. For Roman numerals, the mode can be "U" (upper case) to force the result to upper case, otherwise lower case Roman numerals result. The language may be one of:

The returned text is mixed-case, with capital letters where appropriate, except if you used the "U" mode for Roman numerals. When you use certify, the text does not in any case exceed the maximum size, CERTPK-SIZE, that you specify. If necessary, CERTPK `de-verbalizes' the number starting at the right-hand side until the text is short enough.

When you use date, you can change the CERTPK-SIZE to get a shorter form of the date. If the size is above 12, both month and year will be returned fully. If the size is 11 or 12, the month will be cut to 3 letters. If the size is 10 or less, the year will be cut to 2 digits.

When you use tally, you can set CERTPK-SIZE to zero or a value greater than zero. If zero, the individual digit names will be returned with one space between each. If greater than zero, the size acts as a spacing indicator, ie. tabulation. The CERTPK-DIGITS may be zero (skip leading zeroes) or greater than zero (output that many digits, from the lower end).

An installation can choose to disable some of the languages to minimize the size of the packages. The feedback "L" (language not supported) is returned for such cases.

COMPPK

Source code

Summary: Compresses/expands data to/from an internal compressed format. Processing can be done piece-meal to/from a compressed buffer that is much smaller than the original data area.

How to use: Specify a compression algorithm and the sizes of the original data area and of the area to hold the compressed data. If the compressed buffer is found to be too small, you can save what has been compressed to far and call COMPPK again to continue compression until done.

Limitations: The system you are running on may restrict the size of data areas, typically to 32k or 64k. COMPPK inherits this restriction.

To call COMPPK, define COMPPK-CONTROL and data areas as follows:

            01  COMPPK-CONTROL.
                02  COMPPK-TASK-ID          PIC X(4).
                02  COMPPK-OPERATION        PIC X(1).
                02  COMPPK-FEEDBACK         PIC X(1).
                02  COMPPK-ALGORITHM        PIC X(1).
                02  COMPPK-DATA-SIZE        PIC S9(7)  COMP.
                02  COMPPK-DATA-BASE        PIC S9(7)  COMP.
                02  COMPPK-COMPR-SIZE       PIC S9(7)  COMP.
                02  COMPPK-COMPR-BASE       PIC S9(7)  COMP.

            01  COMPRESSED-BUFFER           PIC X(nnnnn).

            01  Data-area.
                02  Your data...
Define CALL-COMPPK as follows:
            CALL-COMPPK.
                CALL "COMPPK"
                    USING COMPPK-CONTROL
                          Data-area
                          COMPRESSED-BUFFER
                .
You start compression by specifying the algorithm you prefer. If COMPPK-ALGORITHM is a space, a default algorithm is used. Next, the base values are set to zeroes to start at the beginning of the data and of the buffer. Set the size of the data area to compress and of the COMPRESSED-BUFFER. Set COMPPK-OPERATION to "P" (put) and perform CALL-COMPPK.

To expand a compressed buffer, set COMPPK-DATA-BASE and COMPPK-COMPR-BASE both to zero to start at the beginning of the buffers. Set COMPPK-OPERATION to "G" (get) and perform CALL-COMPPK.

COMPPK supports these operations:

COMPPK returns these feedbacks: a space means there were no errors; an "A" means that the supplied algorithm is not supported; a "B" means that the compression buffer size is too small (must be at least 20 characters). An "F" means that the compressed buffer if full. An "E" means that the compressed buffer if empty, ie. that not all data has been expanded. An "O" means that the operation, string size, data mode, or date separator was invalid.
Compression Algorithms
Several algorithms may be used on different systems. The R (RLE) algorithm is implemented on all systems. You are best off not worrying about the inner workings of the package, but below is some information about a typical implementation of RLE. It may be implemented differently on your system.

The RLE (Run-Length Encoding) algorithm works with units. Units are several bytes long (from 2 and up). A unit is not interpreted into smaller parts so can have unusual sizes (eg. 36 bits). A byte is not necessarily 8 bits wide.

Format of encoded data-stream: Algorithm-unit (Rn...), zero or more blocks, null-unit The n following the R gives the current unit size in bytes. Each block is a 1-unit count followed by a data-part, and possibly followed by any number of pad-units. If the count is less than zero, the data-part is a single unit to be repeated -count times (at least 2). If the count is greater than zero, the data-part is that many units to be copied. Pad-units have the value -1. They serve to pad out partially filled buffers. This works because no run is only one unit long. The null-unit ends the data stream.

DATEPK

Source code

Summary: Converts dates between internal (YYYYMMDD) and external (displayable) formats. Will format dates using the desired national conventions.

How to use: Use DATEPK to format a date so that you can print it. You have the same date formatting possibilities as those of SCRNIO. You can also call DATEPK to validate and convert a date in external format into a YYYYMMDD format.

Limitations: DATEPK supports the standard SCRNIO date formatting options. Dates are always stored internally as 8 digits. 0000/00/00 and 9999/99/99 are valid dates, meaning 'no date' and 'forever', respectively.

To call DATEPK, define DATEPK-CONTROL and DATEPK-DATA as follows:

            01  DATEPK-CONTROL.
                02  DATEPK-TASK-ID          PIC X(4).
                02  DATEPK-OPERATION        PIC X(1).
                02  DATEPK-FEEDBACK         PIC X(1)   VALUE SPACE.
                02  DATEPK-DATA-MODE        PIC X(1).
                02  DATEPK-DATE-SEPARATOR   PIC X(1).

            01  DATEPK-DATA.
                02  DATEPK-STRING-SIZE      PIC S9(3)  VALUE COMP +80.
                02  DATEPK-INTERNAL-FORMAT.
                    03  FILLER              PIC X(72).
                    03  DATEPK-DATE-VALUE   PIC 9(08).
                02  DATEPK-EXTERNAL-FORMAT.
                    03  DATEPK-DATE-TEXT    PIC X(80).
Define CALL-DATEPK as follows:
            CALL-DATEPK.
                CALL "DATEPK"
                    USING DATEPK-CONTROL
                          DATEPK-DATA
                .
DATEPK supports these operations: DATEPK returns these feedbacks: a space means there were no errors; an "E" means that the supplied date was invalid. An "O" means that the operation, string size, data mode, or date separator was invalid.

Only DATEPK-STRING-SIZE characters of the internal and external formats are used. Within these areas, the internal date sits at the right, while the external date starts at the left. The DATEPK-STRING-SIZE should always be at least eight. As for SCRNIO, you must specify a valid data mode and date separator.

If you use a datepk-string-size other than 80, you should adjust the data definition accordingly, eg. for size = 8:

            01  DATEPK-DATA.
                02  DATEPK-STRING-SIZE      PIC S9(3)  VALUE COMP +8.
                02  DATEPK-INTERNAL-FORMAT.
                    03  DATEPK-DATE-VALUE   PIC 9(08).
                    03  FILLER              PIC X(72).
                02  DATEPK-EXTERNAL-FORMAT.
                    03  DATEPK-DATE-TEXT    PIC X(80).

GETNBR

Source code

Summary: Extracts a numerical value from a text

string. How to use: Move a string containing somewhere in it a numerical value in external form (eg. " amount $123,456.79 ") to GETNBR- TEXT. Set the decimal-point character ("." in the example above) and call GETNBR. From the data returned you can easily compute the numerial value.

Limitations: At most 18 digits can be handled. The number cannot contain embedded blanks.

To call GETNBR, define GETNBR-CONTROL as follows:

            01  GETNBR-CONTROL.
                  02  SESSION-TASK-ID      PIC X(4).
                  02  GETNBR-OPERATION     PIC X(1).
                  02  GETNBR-FEEDBACK      PIC X(1).
                  02  GETNBR-NUMBER        PIC S9(18).
                  02  GETNBR-SCALE-FACTOR  PIC 9(18).
                  02  GETNBR-TEXT          PIC X(80).
                  02  GETNBR-DECIMAL-POINT PIC X.
Define CALL-GETNBR as follows:
            CALL-GETNBR.
                 CALL "GETNBR"
                     USING GETNBR-CONTROL
                 .
GETNBR supports one operation code - "N" (number). Place in GETNBR-TEXT the string from which the numerical value must be extracted. Supply the decimal-point character ("." or ",") in GETNBR-DECIMAL-POINT. The thousands separator is "the other" one of the two standard decimal-point characters. If the number is integer GETNBR-SCALE-FACTOR will be returned with value 1 and GETNBR-NUMBER is the result, otherwise the resulting numerical value must be computed as THE-RESULT = GETNBR-NUMBER / GETNBR-SCALE- FACTOR; this, of course, also works even if the scale factor is 1. It is your responsibility to ensure that THE-RESULT has enough precision to hold the result without overflow.

GETNBR returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid. A "P" (point character) means that the decimal- point character given was non-standard (in this case "." is assumed). An "S" (syntax error) means that the number is not syntactically correct (GETNBR tries to return a valid number anyway).

The relaxed treatment of syntax errors means that GETNBR can extract dates from texts like 1995/12/11 or 1995-12-11.

MATHPK

Source code

Summary: Computes various mathematical functions such as square root, π, and tangent. All results have 18 digits of precision; 9 before and 9 after the decimal point.

How to use: Call MATHPK when you need access to mathematical functions in a COBOL program. MATHPK provides a wide range of trigonometrical and mathematical functions and mathematical constants such as π.

Limitations: MATHPK works with fixed-point 18-digit numbers; 9 whole digits and 9 decimal digits. To use larger or smaller numbers you must scale up/down before and after calling MATHPK.

To call MATHPK, define MATHPK-CONTROL as follows:

            01  MATHPK-CONTROL.
                02  MATHPK-TASK-ID          PIC X(4).
                02  MATHPK-OPERATION        PIC X(8).
                02  MATHPK-FEEDBACK         PIC X.
                02  MATHPK-RESULT           PIC S9(9)V9(9) COMP.
                02  MATHPK-ARGUMENT         PIC S9(9)V9(9) COMP.
                02  MATHPK-AUXILIARY        PIC S9(9)V9(9) COMP.
Define CALL-MATHPK as follows:
            CALL-MATHPK.
                CALL "MATHPK"
                    USING MATHPK-CONTROL
                .
MATHPK supports these eight-character operation codes: MATHPK returns all results in MATHPK-RESULT. The errors in the function values are generally less than the larger of an absolute error or a relative error of 10-8.

MATHPK returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid. A "D" (domain) means that an argument was outside the valid domain for the operation. An "R" (range) means that the result had too many digits.

Great care has been taken to ensure that the results are the same on all systems. This is especially important for the random number generator, where we must guarantee the same sequence on all systems.

Note, that many other mathematical functions can be derived from the basic set supported here. The tangent function, for example, is just the sine function divided by the cosine function.

Speed of mathpk on some platforms:

                      PC 386/SX25   UNIX RS/6000
            SQRT        4.2 msec      1.58 msec
            POWER       4.0           2.31
            LOG10       4.6           1.24
            ALOG10      2.0           1.30
            SIN/COS     1.6           1.06
            ARCTAN      2.3           1.51
            ARCSIN      5.3           2.33
            EXP         1.5           1.06
            RANDOM      0.9           0.56
            Others      0.0           0.00

NAMEPK

Source code

Summary: Validates COBOL names and filenames; shortens names, and computes a similarity index between two names.

How to use: Call NAMEPK with the word to want to check or to shorten.

Limitations: NAMEPK works with 30-character words. To shorten longer strings or multiple words, use LINEPK.

To call NAMEPK, define NAMEPK-CONTROL as follows:

            01  NAMEPK-CONTROL.
                02  NAMEPK-TASK-ID          PIC X(4).
                02  NAMEPK-OPERATION        PIC X.
                02  NAMEPK-FEEDBACK         PIC X.
                02  NAMEPK-CHECK-DATA.
                    03  NAME-TO-CHECK       PIC X(30).
                    03  NAME-CHECKED        PIC X(30).
                    03  NAMEPK-CHECK-RESULT PIC S9(5)  COMP.
                        88  NAME-IS-INVALID            VALUE IS -1.
                        88  NAME-IS-BLANK              VALUE IS  O.
                        88  NAME-IS-VALID              VALUE IS +1.
                02  FILLER                  REDEFINES  NAMEPK-CHECK-DATA.
                    03  NAME-TO-MATCH       PIC X(30).
                    03  NAME-MATCHED        PIC X(30).
                    03  NAME-SIMILARITY-INDEX
                                            PIC S9(5)  COMP.
                        88  EXACT-MATCH                VALUE +99999.
                        88  REASONABLE-MATCH           VALUE +200 THRU +99998.
                02  FILLER                  REDEFINES  NAMEPK-CHECK-DATA.
                    03  NAME-TO-SHORTEN     PIC X(30).
                    03  NAME-SHORTENED      PIC X(30).
                    03  NAMEPK-MAX-SIZE     PIC S9(5)  COMP.
Define CALL-NAMEPK as follows:
            CALL-NAMEPK.
                CALL "NAMEPK"
                    USING NAMEPK-CONTROL
                .
NAMEPK supports these operations: NAMEPK returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid.

PWRDPK

Source code

Summary: Encrypts a password into a ten-digit number. The algorithms used make it impossible to `crack' the result to get a valid password.

How to use: Supply a password, and other information that is combined to produce an encrypted number. Store only the number in a password file. Later, when a user supplies a password, re-encrypt and compare the result with the stored result.

Limitations: None.

To call PWRDPK, define PWRDPK-CONTROL as follows:

            01  PWRDPK-CONTROL.
                02  PWRDPK-TASK-ID          PIC X(4).
                02  PWRDPK-OPERATION        PIC X      VALUE "E".
                02  PWRDPK-FEEDBACK         PIC X.
                02  PWRDPK-USER-ID          PIC X(08)  VALUE SPACES.
                02  PWRDPK-PASSWORD         PIC X(80).
                02  PWRDPK-CRYPTO-VALUE     PIC 9(10).
                02  PWRDPK-CRYPTO-MASK      PIC 9(10)  VALUE ZERO.
Define CALL-PWRDPK as follows:
            CALL-PWRDPK.
                CALL "PWRDPK"
                    USING PWRDPK-CONTROL
                .
PWRDPK supports one operation, "E" (encrypt). This operation takes the PWRDPK-PASSWORD string of up to 80 characters and reduces it to a ten-digit number, the PWRDPK- CRYPTO-VALUE. It is very difficult, even knowing the algorithm used, to work backwards from the ten-digit number to the original string, although ETK does not pretend that the encryption is unbreakable given enough resources.

The PWRDPK-CRYPTO-MASK (if not zero) and PWRDPK-USER-ID (if not spaces) are included in the encryption process. You can make the result very secure by supplying these values. If several users are allowed to access a password-protected resource, set PWRDPK-USER-ID to spaces.

If you use the PWRDPK-CRYPTO-MASK, be a little subtle. Do not move a display number (which can be detected by examining the executable code) but a computational value. Better still, set PWRDPK-CRYPTO-MASK several times in different parts of the program. Never use the VALUE clause to set PWRDPK-CRYPTO-MASK.

PWRDPK encrypts the password the same way on all systems and produces the same value for PWRDPK-CRYPTO-VALUE.

PWRDPK returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid.

PWRDPK calls the non-portable routine CONVPK. The link points to a "generic" version which you can customize for your platform; alternatively, let us know which platform you are on and we can send you a CONVPK for that.

STRNPK

Source code

Summary: Performs various string-manipulation functions, such as concatenate, substring, and get next word.

How to use: Use STRNPK whenever you need to manipulate short strings. On most systems, STRNPK is efficiently coded in assembler, and is much faster than the equivalent COBOL code.

Limitations: STRNPK works with variable-length strings of up to 80 characters. A string's size is defined by the position of the last non-space character.

To call STRNPK, define STRING-CONTROL as follows:

            01  STRING-CONTROL.
                02  STRING-TASK-ID          PIC X(4).
                02  STRING-OPERATION        PIC X.
                02  STRING-FEEDBACK         PIC X.
                02  STRING-SIZE             PIC S9(3)  COMP.
                02  STRING-TEXT.
                    03  STRING-CHAR         PIC X      OCCURS 80 TIMES.
                02  STRING-CONCAT.
                    03  STRING-FILL-CHAR    PIC X(01).
                    03  STRING-REPLACE-CHAR PIC X(01).
                    03  FILLER              PIC X(78).
Define CALL-STRNPK as follows:
            CALL-STRNPK.
                CALL "STRNPK"
                    USING STRING-CONTROL
                .
STRNPK supports these operations:

STRNPK returns these feedbacks: a space means there were no errors. An "O" means that the specified operation was invalid.

Coding Style

All the packages here are coded in the ETK coding style. Click here to see the rationale for this style.