Compress Data (CPRDATA)


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
Bin(2)



1 = Simple TERSE algorithm
2 = IBM LZ1 algorithm


14 E
Reserved (binary 0)
Char(18)
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. The IBM LZ1 algorithm tends to produce better compression on shorter input strings than 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.

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

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation