Portable Packages

ARITPK Floating point arithmetic
BITPK Bit manipulation
CALCPK Calculator functions
CALRPK Calendar functions
CERTPK Certify number functions
COMPPK Compression function
DATEPK Date encoding/checking
GETNBR Convert text to number
MATHPK Mathematical functions
NAMEPK Name functions
PWRDPK Password authentication
STRNPK String functions
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:

F (float long)
Convert the signed fixed-point long number ARITPK-FIXED-LONG to a normalized floating-point number in ARITPK-FLOAT-RESULT.
E (float short)
Convert the signed fixed-point short number ARITPK-FIXED-SHORT to a normalized floating-point number in ARITPK-FLOAT-RESULT.
N (normalize)
Normalize the floating-point number in ARITPK-FLOAT-RESULT. This means to adjust the mantissa and the exponent until the mantissa is either zero or numerically not less than one-tenth (the left-most digit non-zero).
+ (addition)
Compute ARITPK-FLOAT-RESULT as ADD FLOAT-OPERAND-1 AND FLOAT-OPERAND-2 GIVING FLOAT-RESULT.
- (subtraction)
Compute ARITPK-FLOAT-RESULT as SUBTRACT FLOAT-OPERAND-1 FROM FLOAT-OPERAND-2 GIVING FLOAT-RESULT.
* (multiplication)
Compute ARITPK- FLOAT-RESULT as MULTIPLY FLOAT-OPERAND- 1 AND FLOAT-OPERAND-2 GIVING FLOAT- RESULT.
/ (division)
Compute ARITPK-FLOAT-RESULT as DIVIDE FLOAT-OPERAND-1 INTO FLOAT-OPERAND-2 GIVING FLOAT-RESULT.
P (power)
Compute ARITPK-FLOAT-RESULT as POWER FLOAT-OPERAND-1 OF FLOAT-OPERAND-2 GIVING FLOAT-RESULT (ie. result = operand-2 operand-1). For square root, use OPERAND-1 = 0.5.
S (short)
Convert the signed floating-point ARITPK-FLOAT-RESULT to a signed short fixed-point computational number, ARITPK-FIXED-SHORT, with less range and precision. Range error can occur.
L (long)
Convert the signed floating-point number ARITPK-FLOAT-RESULT to a signed long fixed-point number in ARITPK- FIXED-LONG.
: (compare)
Return sign(FLOAT-OPERAND-2 - FLOAT- OPERAND-1) in ARITPK-FIXED-SHORT, ie. +1 if OPERAND-2 > OPERAND-1, -1 if OPERAND-2 < OPERAND-1, and zero if they are equal.

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:

G (get)
Get the bits of BITPK-NUMBER interpreted as an unsigned 32-bit number. If the number is larger than 32 bits a (R)ANGE feedback is returned and the bit string is all zeroes.
P (pack)
The reverse operation of get. Builds the 32-bit number having the bit string given in BITPK-BITS.
S (set)
For each bit of the bit string given that is a one, set the corresponding bit in BITPK-NUMBER. This is the binary OR operation.
A (and)
For each bit of the bit string given that is a one, set the corresponding bit in BITPK-NUMBER if that bit is also a one, otherwise clear the bit. This is the binary AND operation.
X (xor)
For each bit of the bit string given that is different from the corresponding bit in BITPK-NUMBER, set that bit in BITPK-NUMBER, otherwise clear the bit. This is the binary XOR operation.
C (clear)
For each bit of the bit string given that is a one, clear the corresponding bit in BITPK-NUMBER.
1 (test for 1)
For each bit of the bit string given that is a one, test if the corresponding bit in BITPK-NUMBER is a one. Return an (A)LL feedback if all bits tested were ones, a (N)ONE feedback if none of the bits were ones, or a (S)OME feedback if only some of them were.
0 (test for 0)
For each bit of the bit string given that is a one, test if the corresponding bit in BITPK-NUMBER is a zero. Return an (A)LL feedback if all bits tested were zeroes, a (N)ONE feedback if none of the bits were zeroes, or a (S)OME feedback if only some of them were.

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:

WF ("WHOLE PART OF NUMBER TOO LARGE") A number in the expression had more than 9 digits before the decimal point. The largest number that can be used is 999999999.999999999.
FF ("FRACTION OF NUMBER TOO LARGE") A number had more than 9 digits after the decimal point.
DF ("OPERAND STACK FULL") The internal operand stack overflowed. This is caused by a too-complex expression.
RF ("OPERATOR STACK FULL") The internal operator stack overflowed. This is caused by a too-complex expression or too many levels of parentheses.
RE ("RANGE ERROR") A mathematical function or the `**' operator returned a value or were given a value out of range.

The error codes possible after a syntax error are:

IN ("NOT FUNCTION OR VARIABLE NAME") You probably misspelled a function name.
IC ("INVALID CHARACTER") CALCPK found an invalid character.
LP ("MISSING LEFT PARENTHESIS") There were more right parentheses than left parentheses.
RP ("MISSING RIGHT PARENTHESIS") There were more left parentheses than right parentheses.
IT ("TOKEN INVALID HERE") You probably omitted or doubled a token.
LE ("NOT A LOGICAL EXPRESSION") You can only use `&' or `!' with the result of a comparison or with the values 0 and 1.
MT ("UNEXPECTED END OF EXPRESSION") The expression ended abruptly, with tokens missing.

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:

ABS Compute the absolute value
ACS Compute the arc-cosine in Radians
ASN Compute the arc-sine in Radians
ATN Compute the arc-tangent in Radians
COS Compute the cosine of Radians
EXP Compute the exponential base e
LNE Compute the logarithm base e
LOG Compute the logarithm base 10
NEG Compute the negative of the value
POW Compute the exponent base 10
RND Round the value to the closest whole number
SIN Compute the sine of Radians
SQR Compute the square root of the value
TAN Compute the tangent of Radians

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:

V (validate)
Check that the date is valid. If not, return an "E" (error) feedback.
D (day)
Return the day of the week; 1=Monday, 7=Sunday.
W (week)
Return the week of the year; 0 to 52, where 1 is the first full week.
G (Gregorian)
Convert Julian format or Lillian days into a Gregorian date.
J (Julian)
Convert Gregorian date or Lillian days into the Julian format.
L (Lillian)
Convert Gregorian date or Julian format into Lillian days.

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:

C (certify)
Verbalize CERTPK-NUMBER as fully as possible; 101 in English becomes `One hundred and one'.
T (tally)
Verbalize CERTPK-NUMBER as individual digits; 101 becomes `One zero one'.
D (date)
Write out CERTPK-DATE; 19920101 becomes ` 1 January 1992'.
M (month)
Write out the month part of CERTPK-DATE as a name; 19920101 becomes `January'.

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:

EN English.
FR French.
NL Dutch.
DE German.
ES Spanish.
IT Italian.
PO Portuguese.
FB Belgian French (eg. `Septante' instead of `Soixante-dix').
DA Danish.
NO Norwegian.
SV Swedish.
IS Icelandic.
RM Roman numerals. (only for Certify operation)

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:

P (put)
Put a data area into compressed format. You can select a compression algorithm (see below) or use the default. If you get a feedback of "F" the COMPRESSION- BUFFER is full. In this case, COMPPK- DATA-BASE points to the last piece of data actually compressed; save the compressed buffer somewhere, set COMPPK-COMPR-BASE back to zero and call COMPPK again, until a feedback other than "F" is returned.
G (get)
Get a data area from a compressed buffer. If you get a feedback of "E" the COMPRESSION-BUFFER is empty. In this case, COMPPK-DATA-BASE points to the last piece of data actually expanded; load the compressed buffer with the next portion, set COMPPK- COMPR-BASE back to zero and call COMPPK again, until a feedback other than "E" is returned. COMPPK-ALGORITHM is set to the algorithm that was used to compress the data originally.

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:

D (decode)
Format a date stored as YYYYMMDD into a printable text.
E (encode)
Read a date in external format, and return the corresponding YYYYMMDD. If the century is not shown, it is constrained to be 19 or 20 (using 50 as the discriminating year).

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:

SQRT
Compute MATHPK-RESULT = SQUARE-ROOT (MATHPK-ARGUMENT)
POWER
Compute MATHPK-RESULT = MATHPK-ARGUMENT ** MATHPK-AUXILIARY.
MATHPK-ARGUMENT must be positive.
LOG10
Compute MATHPK-RESULT = LOGARITHM (MATHPK-ARGUMENT) to base ten.
ALOG10
Compute MATHPK-RESULT = ANTI-LOGARITHM (MATHPK-ARGUMENT) to base ten.
SIN
Compute MATHPK-RESULT = SINE (MATHPK- ARGUMENT).
COS
Compute MATHPK-RESULT = COSINE (MATHPK- ARGUMENT).
ARCTAN
Compute MATHPK-RESULT = ARC-TANGENT (MATHPK-ARGUMENT).
The result falls within the range -π/2 to π/2.
ARCSIN
Compute MATHPK-RESULT = ARC-SINE (MATHPK-ARGUMENT).
The result falls within the range -π/2 to π/2.
EXP
Compute MATHPK-RESULT = EXPONENT (MATHPK-ARGUMENT).
RANDOM
Generate, in MATHPK-RESULT, the next random number between 0 and 1 in a pseudo-random sequence determined by a seed value. If no seed is given (using seedrand), the internal default seed value is used and the generator will always yield the same sequence of random numbers. The current seed is stored in MATHPK-ARGUMENT and should not be changed except before a seedrand.
SEEDRAND
Seed the random number generator with the number in MATHPK-ARGUMENT which must be contained in the open interval (0 .. 1).
E
Return the value of e: MATHPK-RESULT = 2.718 281 828.
PI
Return the value of π: MATHPK-RESULT = 3.141 592 654.
GOLDEN
Return the value of the Golden Ratio phi: MATHPK-RESULT = 1.618 033 989.

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:

C (Cobol)
Check that NAME-TO-CHECK is a valid COBOL data name. If the name is valid, NAMEPK sets NAMEPK-CHECK-RESULT to 1. If empty, 0; if invalid, -1. NAME- CHECKED contains the same name, without preceding spaces.
F (filename)
As above, but check for a valid portable filename - a letter followed by up to 7 letters or digits.
M (match)
Compute a similarity index between NAME-TO-MATCH and NAME-MATCHED. This index is a non-negative integer with a perfect match having the largest possible value (99999). If the similarity index is less than 200, it is very unlikely that you would say that the words match. To find the best match for a word in a list, match against each word in the list and keep track of the best result.
S (shorten)
Compress NAME-TO-SHORTEN to fit in NAMEPK-MAX-SIZE. NAMEPK shortens a name by removing redundant letters from the end of the name until the length of the name is equal or less than the size given.

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:

A (append)
Append the STRING-CONCAT to the STRING- TEXT beginning at position STRING-SIZE; if the total size is more than 80 characters, the extra characters are lost. Also return the string's new size plus one, ready for another append operation:
text(ABCD) size(3) concat(VWXYZ) -> text(ABVWXYZ ) size(8)
B (bracket)
Place the STRING-FILL-CHAR before and after the STRING-TEXT (if there is room - at least two extra spaces. Also return the string's new size:
text(ABC) fill(") -> text("ABC") size(5)
C (concatenate)
Append the STRING-CONCAT to the STRING- TEXT; if the total size is more than 80 characters, the extra characters are lost. Also return the string's new size:
text(ABC) concat(abc) -> text(ABCabc) size(6)
D (drop)
Drop the first STRING-SIZE characters from the STRING-TEXT, and left- justifies the rest of the string. Also return the string's new size:
E (edit)
Edit STRING-TEXT up to the last non- blank character if STRING-SIZE is zero, otherwise edit only STRING-SIZE characters. The STRING-FILL-CHAR is replaced by the STRING-REPLACE-CHAR in the edited string. Also return the string's new size:
text(A*B*C) size(0) fill(*) replace(-) -> text(A-B-C) size(5)
F (fill)
Return STRING-TEXT where STRING-FILL- CHAR is repeated STRING-SIZE times. The STRING-SIZE is unchanged:
fill(*) size(10) -> text(**********)
G (get substring)
Search for the first occurrence of STRING-TEXT (delimited by space) within the STRING-CONCAT; if found, return the start position of the substring in STRING-SIZE, else return zero:
text(DE) concat(ABCDEFGCDE) -> size(4)
I (invert)
Invert the STRING-TEXT. Also return the string's size:
text(ABCDEFGH) -> text(HGFEDCBA) size(8)
L (left-justify)
Left-justify the STRING-TEXT by removing STRING-FILL-CHAR characters from the start of the string. Also return the string's new size:
text(00012345) fill(0) -> text(12345) size(5)
M (middle)
Left justify, truncate to STRING-SIZE, then center the STRING-TEXT, padded left and right by STRING-FILL-CHAR characters. The STRING-SIZE is unchanged:
text(**ABC) fill(*) size(9) -> text(***ABC***) size (9)
O (obliterate)
Change all occurrences of STRING-FILL- CHAR in STRING-TEXT to spaces, without re-packing the string. Also return the string's new size:
text(012-ABC) fill(-) -> text(012 ABC) size(7)
P (pack)
Remove all STRING-FILL-CHAR characters in the STRING-TEXT, and compress the result. Also return the string's new size:
text(012-332-1112-34) fill(-) -> text(012332111234) size(12)
R (right-justify)
Right-justify the STRING-TEXT to the size specified, and fill the gap at the left with STRING-FILL-CHAR characters. If the original string is longer than the given size, it is truncated. The STRING-SIZE is unchanged:
text(1550.00) fill(*) size(10) -> text(***1550.00)
S (size)
Return the string's size:
text(ABCDEFGH) -> size(8)
T (truncate)
Truncate the STRING-TEXT to STRING-SIZE characters. The STRING-SIZE is unchanged:
text(ABCDEFGH) size(3) -> text(ABC)
U (unbracket)
Remove the first and last characters from the string (if the string is 2 or more characters long). Also return the string's new size:
text("ABCDEFGH") -> text(ABCDEFGH) size(8)
W (word)
Left-justify the STRING-TEXT, then search for the first word (delimited by STRING-FILL-CHAR). Move the text that follows to STRING-CONCAT. Return the size of the word; zero if the string was used up (empty). To perform repeated word operations, move the STRING-CONCAT back to the STRING-TEXT each time:
text(,,,,A,B,C,) fill(,) -> text(A) size(1) concat(,B,C,)
X (expand)
Move the characters from position STRING-SIZE until the end to the right one position, then insert STRING-FILL-CHAR at position STRING-SIZE. Also return the string's new size:
text(ABCDEFGH) size(3) fill(-) -> text(ABC-DEFGH) size(9)

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.