CSRCMPSC — Compress and expand data

Description

The CSRCMPSC macro performs the following functions:

Compresses data
Expands previously-compressed data

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state, PSW key 8-15
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
Amode:	31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold the local lock of the primary address space and may additionally hold the CMS lock. The caller may hold the CPU lock. No locks are required.
Control parameters:	The CSRYCMPS area, and the dictionary, source area, and target area pointed to by the CSRYCMPS area can all be in the primary address space or, for AR-mode callers, in an address/data space addressable through an ALET. The dictionary and source areas are assumed to be in the same space. In the CSRYCMPS area, the fields that designate the ALETs of the dictionary, source, and target areas should be set to zero by primary mode callers. All parameters may reside in storage above 16 megabytes.

Programming requirements

Before running the CSRCMPSC macro, the program must provide:

A CSRYCMPS area, using the CSRYCMPS mapping macro. The area is specified in the CBLOCK parameter of the CSRCMPSC macro.
Dictionaries for the compress and expand services, using the CSRYCMPD mapping macro. The CSRYCMPS area gives the address of the dictionaries.
A source area, which contains the data to be compressed or expanded. The CSRYCMPS area gives the address of the source area.
A target area, which contains the data after the service has compressed or expanded it. The CSRYCMPS area gives the address of the target area.

See z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the mapping macros.

Restrictions

None.

Input register information

Before issuing the CSRCMPSC macro, the caller must ensure that general purpose register (GPR) 13 contains the address of a standard 72-byte save area in the primary address space.

Before issuing the CSRCMPSC macro, the caller does not have to place any information into any access register (AR), unless running in AR ASC mode. In this case, the caller must ensure that the following ARs contain the specified information:

Register: Contents
13: 0 which designates the primary address space

If the caller is in AR mode and specifies CBLOCK=(n), or if the caller is in primary mode and specifies CBLOCK=(1), the caller must ensure that the following ARs contain the specified information:

Register: Contents
n: The ALET with which the system is to access the CSRYCMPS area. For primary mode callers, the ALET should be 0.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The standard form of CSRCMPSC is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CSRCMPSC.

CSRCMPSC

␢	One or more blanks must follow CSRCMPSC.

CBLOCK=`comp block`	`comp block`: RS-type address, or register (1) - (12).

,RETCODE=`rc`	`rc`: RS-type address, or register (2) - (12).
	Default: No return code processing.

Parameters

The parameters are explained as follows:

CBLOCK=comp block: Specifies the address of the CSRYCMPS area. If register notation is used, the register contains the address of the area. The CSRYCMPS area contains the parameter information for the macro. The area is mapped by DSECT CMPSC in mapping macro CSRYCMPS; see z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for the CSRYCMPS macro.
RETCODE=rc: Specifies the fullword location where the system is to store the return code. If register notation is used, the system stores the return code into the register. In either case, the system stores the return code in GPR 15.

Abend codes

The program issuing CSRCMPSC may receive the listed abend codes. See z/OS MVS System Codes.

0C4

The program may get this completion code if the system cannot access the CSRYCMPS area, source area, target area, or dictionary.

0C6

The program may get this completion code if the CMPSC_SYMSIZE field in the CSRYCMPS area does not contain 1-5.

This completion code is received only if bit CVTCMPSC in mapping macro CVT is on.

0C7

The dictionary is built incorrectly. The program may receive this completion code in the following circumstances:

If the length of a string to be represented by a single compression symbol, encountered during a compression operation, exceeds 260 characters.
If a dictionary entry has more than 260 total child characters.
If the child count in a dictionary entry indicates more than 6 child characters.
If the number of extension characters for a dictionary entry with 0 or 1 child characters exceeds 4.
If a sibling descriptor dictionary entry has a sibling count of 0.
If expansion of a compression symbol uses more than 260 characters.
If expansion of a compression symbol uses more than 127 dictionary entries.

In all these cases, the programmer needs to fix the dictionary.

This completion code is received only if bit CVTCMPSC in mapping macro CVT is on.

Return and reason codes

When the CSRCMPSC macro returns control to the program, the RETCODE parameter fullword and GPR 15 contain one of the following hexadecimal return codes.

Hexadecimal Return Code	Meaning and Action
0	Meaning: Successful completion. Source operand was completely processed. Action: None.
4	Meaning: Source operand was not completely processed. No room is left in the target operand. Action: Specify a larger target operand. Or provide another area for the target operand. Issue the macro again to resume processing of the operation.
10	Meaning: Program error. A field in the CSRYCMPS area does not contain a value. Action: Provide values in the CMPSC_DICTADDR, CMPSC_TARGETADDR, and CMPSC_SOURCEADDR fields.
14	Meaning: Program error. The symbol size in the CSRYCMPS area does not have a value of 1 through 5. Action: Provide a value of 1 through 5 in the CMPSC_SYMSIZE field.
18	Meaning: The target area for compression or the source area for expansion is not large enough to hold even one compression symbol. The length of the area is specified in the CSRYCMPS area. Action: If this result is expected, no action is required. Otherwise, provide a larger value in the CMPSC_TARGETLEN field for compression or the CMPSC_SOURCELEN field for expansion.
1C	Meaning: Program error. The length of the string represented by a single compression symbol exceeds the limit of 260 bytes. Action: Fix the dictionary.
20	Meaning: Program error. The number of child characters for a compression dictionary entry exceeds 260. Action: Fix the dictionary.
24	Meaning: Program error. A compression dictionary entry indicates that it contains more than 6 child characters, not including sibling characters. Action: Fix the dictionary.
28	Meaning: Program error. The number of extension characters for a compression dictionary entry with 0 or 1 child characters exceeds 4. Action: Fix the dictionary.
2C	Meaning: Program error. A sibling descriptor compression dictionary entry has a count of 0. Action: Fix the dictionary.
30	Meaning: Program error. Expansion of a compression symbol used more than 127 dictionary entries. Action: Fix the dictionary.

Example 1

Compress a data area. Note that the expansion dictionary must immediately follow the compression dictionary, and both must be aligned on page boundaries.

         LA    2,MYCBLOCK               Get address of parm
         USING CMPSC,2
         XC    CMPSC(CMPSC_LEN),CMPSC   Clear block
         OI    CMPSC_FLAGS_BYTE2,CMPSC_SYMSIZE_5 Set size
*                        Symbol size is 5+8. Dictionary has
*                        2**(5+8) entries
         L     3,DICTADDR
         ST    3,CMPSC_DICTADDR         Set dictionary address
         L     3,COMPADDR
         ST    3,CMPSC_TARGETADDR       Set compression area
         L     3,COMPLEN
         ST    3,CMPSC_TARGETLEN        Set compression length
         L     3,EXPADDR
         ST    3,CMPSC_SOURCEADDR       Set expansion area
         L     3,EXPLEN
         ST    3,CMPSC_SOURCELEN        Set expansion length
         LA    3,WORKAREA
         ST    3,CMPSC_WORKAREAADDR     Set work area address
         CSRCMPSC CBLOCK=CMPSC
         DROP  2
 .
 .
         DS    0F        Align parameter on word boundary
MYCBLOCK DS    (CMPSC_LEN)CL1    CBLOCK parameter
COMPADDR DS    A         Output compression area
COMPLEN  DS    F         Length of compression area
EXPADDR  DS    A         Input expansion area
EXPLEN   DS    F         Length of expansion area
DICTADDR DS    A         Address of compression dictionary
         DS    0D        Doubleword align work area
WORKAREA DS    CL192     Work area
         CSRYCMPS ,

Example 2

Expand a data area. Note that the expansion dictionary must be aligned on a page boundary.

         LA    2,MYCBLOCK               Get address of parm
         USING CMPSC,2
         XC    CMPSC(CMPSC_LEN),CMPSC   Clear block
         OI    CMPSC_FLAGS_BYTE2,CMPSC_SYMSIZE_5 Set size
*                        Symbol size is 5+8. Dictionary has
*                        2**(5+8) entries
         OI    CMPSC_FLAGS_BYTE2,CMPSC_EXPAND  Do expansion
         L     3,EDICTADDR
         ST    3,CMPSC_DICTADDR         Set dictionary address
         L     3,EXPADDR
         ST    3,CMPSC_TARGETADDR       Set expansion area
         L     3,EXPLEN
         ST    3,CMPSC_TARGETLEN        Set expansion length
         L     3,COMPADDR
         ST    3,CMPSC_SOURCEADDR       Set compression area
         L     3,COMPLEN
         ST    3,CMPSC_SOURCELEN        Set compression length
         LA    3,WORKAREA
         ST    3,CMPSC_WORKAREAADDR     Set work area address
         CSRCMPSC CBLOCK=CMPSC
         DROP  2
 .
 .
         DS    0F        Align parameter on word boundary
MYCBLOCK DS    (CMPSC_LEN)CL1    CBLOCK Parameter
EXPADDR  DS    A         Output expansion area
EXPLEN   DS    F         Length of expansion area
COMPADDR DS    A         Input compression area
COMPLEN  DS    F         Length of compression area
EDICTADDR DS   A         Address of expansion dictionary
         DS    0D        Doubleword align work area
WORKAREA DS    CL192     Work area
         CSRYCMPS ,

Example 3

When using register notation in the CBLOCK parameter, the program must place both the address and ALET into a GPR/AR pair. This is true whether you are running in AR or primary ASC mode.

.
.
        LAE   2,MYCBLOCK              Set address *and* ALET
        CSRCMPSC CBLOCK=(2)           Issue operation
.
.