|
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.
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
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
.
.
|