Compress Data (CPRDATA)

Edit online

Instruction Syntax

Op Code (Hex) Operand 1
1041 Compress data template
Operand 1: Space pointer.

Bound Program Access 
Built-in number for CPRDATA is 107.
CPRDATA (
         compress_data_template   : address
)

Description:

The instruction compresses user data of a specified length. Operand 1 identifies a template which identifies the data to be compressed. The template also identifies the result space to receive the compressed data.

The compress data template must be aligned on a 16-byte boundary. The format is as follows:

Offset
Dec Hex Field Name Data Type and Length
0 0 Source length Bin(4)
4 4 Result area length Bin(4)
8 8 Actual result length Bin(4) +
12
C
Compression algorithm
1 =
Simple TERSE algorithm
2 =
IBM LZ1 algorithm
3 =
zlib deflate algorithm
Bin(2)
14
E
zlib deflate bias
0 =
Balance speed and compression size
1 =
Bias toward speed
2 =
Bias toward compression size
3 =
No compression
Bin(1)
15 F Reserved (binary 0) Char(17)
32 20 Source space pointer Space pointer
48 30 Result space pointer Space pointer
64
40
--- End ---
Note: The input value associated with template fields annotated with a plus sign (+) are ignored by the instruction; these fields are updated by the instruction to return information about instruction execution.

The data at the location specified by the source space pointer for the length specified by the source length is compressed and stored at the location specified by the result space pointer. The actual result length is set to the number of bytes in the compressed result. The source data is not modified.

The value of both the source length field and result area length field must be greater than or equal to zero. If either of these conditions is not met, a template value invalid (hex 3801) exception is signalled. If the length of the compressed result is greater than the value in the result area length field, a materialization length invalid (hex 3803) exception is signalled.

The compression algorithm field specifies the algorithm used to compress the data. Generally, the zlib deflate algorithm tends to compress better than the IBM LZ1 algorithm or the simple TERSE algorithm. The zlib deflate algorithm also allows a bias to be specified as a hint to the system to choose between speed of compression versus compression size. If the zlib hardware acceleration feature is available on the machine, it might be used when the zlib deflate algorithm is specified. No hardware acceleration feature is available for the IBM LZ1 algorithm or the simple TERSE algorithm. The algorithm choice is stored in the compressed output data so the Decompress Data (DCPDATA) instruction will automatically select the correct decompression algorithm.

The zlib deflate bias field can be used to select the compression level for the zlib deflate algorithm. This field must be 0 for the other compression algorithms; otherwise, a template value invalid (hex 3801) exception is signalled. The bias specifies whether compression should bias toward speed or compression size. Valid zlib deflate bias values are:
0 =
The compression level will be balanced between speed and compression size.
1 =
The compression will bias toward speed, at the expense of compression size.
2 =
The compression will bias toward compression size, at the expense of speed.
3 =
The data will not be compressed; however, the output will be packaged as though the zlib deflate algorithm was used. This way the Decompress Data (DCPDATA) instruction can still be used on the CPRDATA output.
Specifying a value other than 0, 1, 2 or 3 causes a template value invalid (hex 3801) exception to be signalled.

The zlib deflate algorithm is implemented in software and it can be accelerated if the zlib hardware acceleration feature is available on the machine. The zlib hardware acceleration feature can substantially speed up compression times when compared to using software; however, it might do so at the expense of increased compression size. Therefore, even for the same bias setting, the size of the compressed output could differ depending on whether the zlib hardware acceleration is used or not (which can vary between calls). If hardware acceleration is available, it may be used for zlib deflate bias values of 0 and 1, and only the software implementation is used for zlib deflate bias values of 2 and 3. This is to ensure a smaller compression size for the zlib deflate bias value of 2, which prioritizes a smaller size over faster compression.

Only scalar (non-pointer) data is compressed, so any pointers in the data to be compressed are destroyed in the output of the Compress Data instruction.

Authorization Required

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 10 Damage Encountered
    • 1044 Partial System Object Damage
  • 1C Machine-Dependent
    • 1C03 Machine Storage Limit Exceeded
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 22 Object Access
    • 2202 Object Destroyed
    • 2203 Object Suspended
    • 2208 Object Compressed
    • 220B Object Not Available
  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 3801 Template Value Invalid
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
  • 45 Heap Space
    • 4503 Heap Space Full