CSRCESRV — Compress and expand data

Description

Use the CSRCESRV macro to compress data and restore the data to its original state when you need it. The CSRCESRV macro has three different services:

Query (SERVICE=QUERY), to obtain the information your program needs to invoke data compression or data expansion
Data compression (SERVICE=COMPRESS), to achieve reduced data volume
Data expansion (SERVICE=EXPAND), to expand data previously compressed by the data compression service.

Before attempting to use the CSRCESRV macro, see “Using Data Compression and Expansion Services” in z/OS MVS Programming: Assembler Services Guide for a description of the data compression, expansion, and query services, and the conditions under which programs can exploit these services.

To invoke the CSRCESRV macro for either data compression or data expansion, first invoke CSRCESRV with SERVICE=QUERY. Follow these steps:

Load the general purpose registers (GPRs) with information required by SERVICE=QUERY.
Invoke the CSRCESRV macro with SERVICE=QUERY.
Load the GPRs with information required by SERVICE=COMPRESS (or SERVICE=EXPAND).
Invoke the CSRCESRV macro with SERVICE=COMPRESS (or SERVICE=EXPAND).
If all the input data has not been processed, continue to re-invoke the service until processing is complete.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state with PSW key 8-15
Dispatchable unit mode:	Task or SRB mode.
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 locks, but is not required to hold any.
Control parameters:	None.

Programming requirements

None.

Restrictions

None.

Input register information for SERVICE=QUERY

Before issuing the CSRCESRV macro with the SERVICE=QUERY parameter, the caller must ensure that the following GPRs contain the specified information:

Register: Contents
0: The run length encoding algorithm. Specify either 0 or 1.
13: The 31-bit address of a standard 18-word save area. If your program is running in AR ASC mode, set AR 13 to specify the ALET to be used to qualify GPR 13.

Output register information for SERVICE=QUERY

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: A value of 1 to indicate that the run length encoding algorithm will be used.
1: The length of the work area required by the algorithm. This value might be zero if the service does not require a work area.
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

Input register information for SERVICE=COMPRESS

Before issuing the CSRCESRV macro with the SERVICE=COMPRESS parameter, the caller must ensure that the following GPRs contain the specified information:

Register: Contents
1: The 31-bit address of a work area, if one is needed. The value returned in GPR 1, when you issue CSRCESRV with SERVICE=QUERY, indicates the size of the required work area. If your program is running in AR ASC mode, set AR 1 to specify the ALET to be used to qualify the GPR.
2: The 31-bit address of the uncompressed input data block. If your program is running in AR ASC mode, set AR 2 to specify the ALET to be used to qualify the GPR.
3: The length of the uncompressed input data block.
4: The 31-bit address of the output data block to hold the compressed data. If your program is running in AR ASC mode, set AR 4 to specify the ALET to be used to qualify the GPR.
5: The length of the output data block.
13: The 31-bit address of a standard 18-word save area. If your program is running in AR ASC mode, set AR 13 to specify the ALET to be used to qualify the GPR.

Output register information for SERVICE=COMPRESS

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Unchanged
2: The 31-bit address of the byte following the last input byte processed
3: The number of bytes of uncompressed data not processed
4: The 31-bit address of the byte following the last output byte
5: The number of bytes in the output data block into which output was not stored
6-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

Input register information for SERVICE=EXPAND

Before issuing the CSRCESRV macro with the SERVICE=EXPAND parameter, the caller must ensure that the following GPRs contain the specified information:

Register: Contents
1: The 31-bit address of a work area, if one is needed. The value returned in GPR 1, when you issue CSRCESRV with SERVICE=QUERY, indicates the size of the required work area. If your program is running in AR ASC mode, set AR 1 to specify the ALET to be used to qualify the GPR.
2: The 31-bit address of the compressed input data block. If your program is running in AR ASC mode, set AR 2 to specify the ALET to be used to qualify the GPR.
3: The length of the compressed input data block.
4: The 31-bit address of the output data block to hold the expanded data. If your program is running in AR ASC mode, set AR 4 to specify the ALET to be used to qualify the GPR.
5: The length of the output data block.
13: The 31-bit address of a standard 18-word save area. If your program is running in AR ASC mode, set AR 13 to specify the ALET to be used to qualify the GPR.

Output register information for SERVICE=EXPAND

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Unchanged
2: The 31-bit address of the byte following the last input byte processed
3: The number of bytes of compressed data not processed
4: The 31-bit address of the byte following the last output byte
5: The number of bytes in the output data block into which output was not stored
6-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

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The CSRCESRV macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede CSRCESRV.

CSRCESRV

␢	One or more blanks must follow CSRCESRV.


SERVICE=QUERY SERVICE=COMPRESS SERVICE=EXPAND

,VECTOR=`(reg)`	`reg`: register (2) - (12).

Parameters

The parameters are explained as follows:

SERVICE=QUERY

SERVICE=COMPRESS

SERVICE=EXPAND

Specifies the requested service.

SERVICE=QUERY invokes the query service, which determines the following:

Whether data compression is supported by the system currently installed
The size of the work area required by the compression or expansion service.

You need the above information before you can invoke the macro with SERVICE=COMPRESS or SERVICE=EXPAND.

SERVICE=COMPRESS invokes the data compression service, which compresses a given block of data, and stores the compressed data in an output area. You must obtain storage for this output area, and for a work area if SERVICE=QUERY returns a nonzero value in GPR 1. SERVICE=COMPRESS will compress as much of the input data as possible. It returns to the caller when either of the following has occurred:

It has compressed all the input data
It has completely filled the output area with the compressed data.

SERVICE=EXPAND invokes the data expansion service, which expands data that was previously compressed by the data compression service, and stores that data in its original form in an output area. You must obtain storage for this output area, and for a work area if SERVICE=QUERY returns a nonzero value in GPR 1. SERVICE=EXPAND will expand as much of the input data as possible. It returns to the caller when either of the following has occurred:

It has expanded all the input data
It has completely filled the output area with the expanded data.

,VECTOR=(reg)

reg is the GPR that your program loads with the entry point address of the CSRCEXA load module. This load module resides in SYS1.MIGLIB.

ABEND codes

None.

Return and reason codes

When control is returned from CSRCESRV, GPR 15 (and return_code) contains one of the following return codes:

Table 1. Return Codes for SERVICE=QUERY
Hexadecimal Return Code	Meaning and Action
00	Meaning: The requested algorithm is supported. This means that both compression and expansion are supported. Action: None.
04	Meaning: The requested algorithm is supported only for data expansion. Action: None.
0C	Meaning: Program error. The requested algorithm is not supported by this level of MVS™. Action: Specify the appropriate input value and rerun the program.
10	Meaning: Program error. The algorithm number was negative. Action: Specify the appropriate input value and rerun the program.

Table 2. Return Codes for SERVICE=COMPRESS
Hexadecimal Return Code	Meaning and Action
00	Meaning: All input data was compressed. Action: None.
04	Meaning: Program error. Not all input data was compressed because the output area was too small. Action: Examine the information returned in the GPRs. Either make a follow-up request to have the rest of the uncompressed data processed, or issue the macro with a larger output area.
0C	Meaning: Program error. Either the input or output length was negative. Action: Inspect the contents of the GPRs to determine which value is in error. Specify the appropriate input values and rerun the program.

Table 3. Return Codes for SERVICE=EXPAND
Hexadecimal Return Code	Meaning and Action
00	Meaning: All input data was expanded. Action: None.
04	Meaning: Program error. Not all input data was expanded because the output area was too small. Action: Examine the information returned in the GPRs. Either make a follow-up request to have the rest of the compressed data processed or issue the macro with a larger output area.
08	Meaning: Program error. The data was not expanded because it was compressed by an up-level version of the data compression service, using an algorithm not understood by this version of the data expansion service. Action: Check to see if all the input values were correct. Ensure that the input data was compressed by the appropriate data compression service and that the appropriate data expansion service was invoked. If the problem persists, record the return code and supply it to the appropriate IBM® support personnel.
0C	Meaning: Program error. Either the input or output length was negative. Inspect the register contents to make this distinction. Action: Specify the appropriate input values and rerun the program.
10	Meaning: Program error. Not all the data was expanded because the input data was not compressed by the data compression service. Action: Check to see if all the input values were correct. Ensure that the input data was compressed by the appropriate data compression service and that the appropriate data expansion service was invoked. If the problem persists, record the return code and supply it to the appropriate IBM support personnel.