home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / cobol / library / comp / comp.doc next >
Text File  |  1990-07-24  |  8KB  |  163 lines
  1. ******************************************************************************
  2. *                                                                            *
  3. * COMPS.LIB - Copyright 1990 Michael P. Deignan. All Rights Reserved.        *
  4. *                                                                            *
  5. * This product may be freely distributed as long as all copyright notices    *
  6. * appear intact. Source code is available to qualified users. Contact the    *
  7. * author, with either bug reports, or for source information, at:            *
  8. *                                                                            *
  9. * Internet:     mpd@anomaly.sbs.com                                         *
  10. * UUCP:          ...!uunet!anomaly.sbs.com!mpd                               *
  11. * 'Anomaly':     +1 401 455 0347 Telebit Trailblazer Plus                    *
  12. *                                                                            *
  13. ******************************************************************************
  14. *                                                                            *
  15. * COMPS.LIB contains a series of routines which allow the user to store      *
  16. * data in the same format as IBM mainframe equipment does, as created by     *
  17. * IBM's COBOL compiler (thus, are generally compatible with just about any   *
  18. * language on an IBM mainframe, unless you do odd things in assembler with   *
  19. * these variable types. The routines allow you, the user, to retrieve and    *
  20. * store information as COMP1, COMP2, COMP3, COMP. Using these utilities, you *
  21. * can download data from the mainframe, manipulate it on the PC, and then    *
  22. * transfer manipulated data back to the mainframe.                           *
  23. *                                                                            *
  24. * The user merely passes a character string (compressed binary number) or    *
  25. * a numeral value to these routines. The routines then determine whether     *
  26. * the conversion has to be "from" compressed-binary to numeric, or from      *
  27. * numeric to a compressed-binary string.                                     *
  28. *                                                                            *
  29. * Those unfamiliar with the internal storage representation of these formats *
  30. * should review their appropiate IBM documention, in conjunction with the    *
  31. * source code for these functions, and the technical description of how each *
  32. * function operates, in COMPTECH.DOC (available to registered users only.)   *
  33. *                                                                            *
  34. * There are two additional functions in this library, which exist for as     *
  35. * support functions to the four main functions. These functions are COMP4()  *
  36. * which is the same as COMP() except uses all 64 bits for positive values,   *
  37. * instead of using the hi-order bit for a sign bit. The second function is   *
  38. * TWOS_COMPLIMENT(), which will calculate the two's compliment of a value    *
  39. * passed to it. IBM stored negative numbers in two's compliment form.        *
  40. *                                                                            *
  41. ******************************************************************************
  42.  
  43. Function:        Usage Description:
  44. ---------        ----------------------------------------------------
  45. COMP(<expN>)        Convert a display numeric value to binary. Result
  46.             returned will be either a fullword (4 bytes) or a
  47.             doubleword (8 bytes) binary value in a character
  48.             string. Numeric Limitation: +/- 2^32
  49.  
  50. COMP(<expC>)        Convert a binary value to display numeric. Result
  51.             returned will be a positive or negative numeric value.
  52.  
  53. COMP1(<expN>)        Convert display numeric to Internal Floating Point,
  54.             Short Precision. Returns a character string of 4 bytes
  55.             (one fullword).
  56.  
  57. COMP1(<expC>)           Convert Internal Floating Point 4-character Short
  58.             Precision string to display numeric. Returns a numeric
  59.             value of variable length with decimal precision, if
  60.             appropiate (depending on input.)
  61.  
  62. COMP2(<expN>)        Convert display numeric to Internal Floating Point,
  63.             Long Precision. Returns a character string of 8 bytes
  64.             (two fullwords).
  65.  
  66. COMP2(<expC>)           Convert Internal Floating Point 4-character Long
  67.             Precision string to display numeric. Returns a numeric
  68.             value of variable length with decimal precision, if
  69.             appropiate (depending on input.)
  70.  
  71. COMP3(<expN>)        Convert a display numeric value to packed decimal,
  72.             signed. This routine returns a character string of
  73.             variable length (depending on input) with appropiate
  74.             sign bits in the LSB.
  75.  
  76. COMP3(<expC>)        Convert a packed decimal character string to display
  77.             numeric. The returned result is a numeric value,
  78.             signed negative if necessary.
  79.  
  80. COMP4(<expN>)        Convert a display numeric value to binary. Result
  81.             returned will be either a fullword (4 bytes) or a
  82.             doubleword (8 bytes) binary value in a character
  83.             string. Numeric Limitation: +2^64. Signs are ignored
  84.             by this routine.
  85.  
  86. COMP4(<expC>)        Convert a binary value to display numeric. Result
  87.             returned will always be a positive numeric value.
  88.  
  89.  
  90. TWOS_COMPL(<expC>)    Calculate the twos compliment of a character string's
  91.             binary value. Returns a character string of equal
  92.             length to the caller.
  93.  
  94. BINARY_ERR(<expC>)    Display An Error Message On Line 0. Forces termination
  95.             of the program. This is a rudimentary routine, which 
  96.             should be rewritten by the user to provide error
  97.             handling on an application-by-application basis. This
  98.             function does not return to the caller.
  99.  
  100. ******************************************************************************
  101. *                                                                            *
  102. *                               C A V E A T S                                *
  103. *                                                                            *
  104. ******************************************************************************
  105.  
  106. Function: COMP
  107.  
  108. This routine can only handle values up to 2^32 power. It uses the high-order
  109. bit as a sign bit, thus will return a positive or negative value. It will 
  110. return a string (for numeric->binary conversion) which is either a fullword
  111. (4 bytes) or two full-words (8 bytes). A high-bit set indicates a negative 
  112. value.
  113.  
  114. -=-
  115.  
  116. Function: COMP1
  117.  
  118. As this is a short-precision routine, it will always return 4 bytes when
  119. converting to COMP1 from numeric display, and expects 4 bytes if converting
  120. back to numeric display. Providing less than 4 bytes of short-precision data
  121. may yield odd results.
  122.  
  123. -=-
  124.  
  125. Function: COMP2
  126.  
  127. As this is a long-precision routine, it will always return 8 bytes when
  128. converting to COMP2 from numeric display, and expects 8 bytes if converting
  129. back to numeric display. Providing less than 8 bytes of long-precision data
  130. may yield odd results.
  131.  
  132. -=-
  133.  
  134. Function: COMP3
  135.  
  136. This routine is slightly different than IBM's COMP-3 data type, however, is 
  137. backwards compatible with it. The primary difference is that packed decimal 
  138. values created by this routine will have the number of decimals stored in the
  139. sign half-byte, which will be re-used to properly place the decimal point upon
  140. uncompression.
  141.  
  142. Should a character field be passed to this routine which contains a non-
  143. packed-decimal value, then the routine will return '0' for the decimal
  144. number.
  145.  
  146. When handling decimals, a maximum of seven decimals places are accounted
  147. for. Any data beyond the seventh decimal is trucated by the function.
  148.  
  149. Since mainframes use logical decimal-point placement (via a PIC ...v...
  150. clause) data from a mainframe will be treated as whole numbers.
  151.  
  152. -=-
  153.  
  154. Function: COMP4
  155.  
  156. This routine handles values up to 2^64 power. It is not "compatible" with 
  157. IBM's COMP4 function, as COMP4 is generally as a "COMP" on most mainframes
  158. anyway. This routine will return a double-word (8 bytes) to the caller.
  159.  
  160. ******************************************************************************
  161. *                                End Of Text                                 *
  162. ******************************************************************************
  163.