Preface
INFOPAK MULTI ENVIRONMENTS was developed to transfer compressed data from or to a mainframe system running the MVS operating system to or from any other environment where a program written in C language can be executed.
INFOPAK MULTI ENVIRONMENTS provides a compression/decompression entry point to be used on an MVS system as well as an API having the same characteristics for any non-MVS environment.
note
The internal format of data on a mainframe is EBCDIC but in most of the other environments, it is ASCII, therefore additional processing other than compression/decompression processing is necessary to convert from EBCDIC to ASCII or from ASCII to EBCDIC depending on the transmission direction.
Installation
What you received
The material for installation contains:
-
one 3480 cartridge with installation JCL for MVS.
-
a floppy disk or a cartridge for the non-MVS part.
Installation of the MVS part.
The JCL contains a confidential code with an expiration date corresponding to the end of the test period. When a test version becomes a permanent version, Infotel will send you a new confidential code.
The following steps are to be performed:
-
Create the JCL using the installation sheet as a model. Please verify that the CPU serial numbers on the installation sheet are correct.
-
Insert a JOB card in front of the deck.
-
Complete the installation sheet with the actual library names. If you are using temporary libraries, please insure that all members are copied to the final libraries when making the permanent installation.
-
Change the name SYSDA (temporary files), if necessary.
-
Mount the cartridge as required.
-
Submit the job.
-
Check the return code (return code = 0).
-
Copy the product tape datasets to permanent disk as described in steps 1 and 2 of "Reinstallation without the product tape". These disk datasets should be excluded from migration products as they are required for CPU upgrades and Disaster Recovery procedures.
If the job has abended there will usually be a self explanatory message in the SYSOUT. If this message indicates that an abnormal return code was issued by a utility program, the explanation will usually be found at the end of the listing (SYSPRINT).
The most common errors are:
-
an erroneous confidential code,
-
a misspelled DDNAME or DSNAME,
-
an insufficient region size (see EXEC card),
-
a SYSLIB DD card pointing to wrong library.
The INFCMRV0 module (DDNAME MVSLOAD of the installation JCL) has an entry point INFCMR00 to perform compression/decompression of a buffer (memory field).
Installation of the non-MVS part.
The floppy disk (or cartridge) contains three files:
{wrapper="1" role="DL"}
-
INFOPAK.H
"header C" describes the compression/decompression function and the macro for the conversion ASCII <-> EBCDIC,
-
INFOPAK.OBJ
is the object file that contains the compression function,
-
INFOPAKC.C
contains an example for a use in the C language.
These files are in ASCII format (except of INFOPAK.OBJ which is in binary format). During installation these files are to be copied onto the target environment.
Using INFCMRV0 on an MVS system.
The INFCMRV0 module (DDNAME MVSLOAD in the installation JCL) has an entry point INFCMR00 to perform the compression or decompression of an entry data area buffer to an output data area. This entry point is reentrant and can be called from any user program.
note
For static calls, the module INFCMRV0 must be link-edited with the user program. For dynamic calls INFCMRV0 must be located in a STEPLIB, LINKLIST or LPA.
Description of the INFCMR00 entry point.
The INFCMR00 entry point parameters are described below:
CALL INFCMR00, name of the entry point X
(FUNC, function code X
INPUT, input area X
INSIZE, length of input area X
OUTPUT, output area X
OUTSIZE),VL length of output area
This entry point is called with five parameters:
{wrapper="1" role="DL"}
-
FUNC
Function code
This word (PIC S9(8) COMP in COBOL) indicates whether this is compression or decompression. This word must be initialized with zero for compression and 4 for decompression.
-
INPUT
Input area
Input data to be compressed or decompressed depending on the function code.
-
INSIZE
Length of the input area
This word (PIC S9(8) COMP in COBOL) contains the length of the input area.
-
OUTPUT
Output area
Depending on the function code, this area contains the compressed or the decompressed data after the call.
-
OUTSIZE
Length of the output area
This word (PIC S9(8) COMP in COBOL) indicates the required length of the output area. When returning control to the calling program, INFCMR00 places the actual length of the compressed or decompressed output into this field. If the length specified here initially was insufficient (i.e. the resultant compressed or decompressed data is longer than the output length that was specified), INFCMR00 fills the output area with the compressed or decompressed data up to the insufficient length and issues a return code (RETURN-CODE in COBOL) of 4.
The return code values are described below:
{wrapper="1" role="DL"}
-
0
step (compression or decompression) was performed.
-
4
step incomplete, the output buffer is too small, the data is truncated.
Example with Cobol
*
* DATA
*
01 INSIZE PIC S9(08) COMP.
01 INPUT PIC X(100).
01 OUTSIZE PIC S9(08) COMP.
01 OUTPUT PIC X(101).
01 FUNC PIC S9(08) COMP.
*
* 1) COMPRESSION
*
*
MOVE 0 TO FUNC. COMPRESSION
MOVE 100 TO INSIZE. LENGTH OF THE DATA TO BE COMPRESSED
MOVE 101 TO OUTSIZE. LENGTH OF THE OUTPUT DATA
CALL 'INFCMR00' USING FUNC INPUT INSIZE OUTPUT OUTSIZE.
*
* 2) DECOMPRESSION
*
*
MOVE 4 TO FUNC. DECOMPRESSION
MOVE OUTSIZE TO INSIZE. REINITIALIZATION OF LENGTH
MOVE OUTPUT TO INPUT. AND INPUT AREA
MOVE 101 TO OUTSIZE. LENGTH OF OUTPUT DATA
CALL 'INFCMR00' USING FUNC INPUT INSIZE OUTPUT OUTSIZE.
The above example illustrates the compression of an area followed by a decompression. During the decompression the length of the input area was reinitialized with the result provided by INFCMR00 (length of the compressed area) as well as the input area with the compressed data. The length of the output area is systematically initialized before the call.
note
The output area is one byte longer than the input area in order to ensure that the length is sufficient for the compression. Indeed, when compression is impossible (random binary area), INFOPAK copies again the input area and adds one byte. If decompression takes place, the original area is restored.
Example with assembler 370
*
* DATA
*
INSIZE DS F
INPUT DC CL100' '
OUTSIZE DS F
OUTPUT DS CL101
FUNC DS F
*
* 1) COMPRESSION
*
*
LA 7,0
ST 7,FUNC FUNCTION CODE
LA 7,100
ST 7,INSIZE INPUT LENGTH
LA 7,101
ST 7,OUTSIZE OUTPUT LENGTH
CALL INFCMR00,(FUNC,INPUT,INSIZE,OUTPUT,OUTSIZE),VL
*
* 2) DECOMPRESSION
*
*
LA 7,4
ST 7,FUNC FUNCTION CODE
L 7,OUTSIZE
ST 7,INSIZE INPUT LENGTH
BCTR 7,0
EX 7,EXMOVE REINITIALIZES THE INPUT AREA
LA 7,101
ST 7,OUTSIZE OUTPUT LENGTH
CALL INFCMR00,(FUNC,INPUT,INSIZE,OUTPUT,OUTSIZE),VL
BR 14
EXMOVE MVC INPUT(0),OUTPUT
Use in a non-MVS environment
The compression/decompression of data in a non-MVS environment is performed by calling the function infcmr00 of the INFOPAK.OBJ object module.
The header file INFOPAK.H contains the description of this function as well as the description of the conversion macro infxlt allowing to convert ASCII <---> EBCDIC.
note
The object file INFOPAK.OBJ must be linked with the user program.
Description of the infcmr00 function
The function infcmr00 performs compression/decompression of an input buffer to an output buffer, the characteristics of this function are described below:
int infcmr00 ( long int *function , /* call function */
char *input , /* input area */
long int *insize ,/* length input area */
char *output, /* output area */
long int *outsize /* length output area */
) ;
This function is called with five parameters (pointers):
{wrapper="1" role="DL"}
-
function
Function code
This word (long int in C language) indicates whether this is compression or decompression. This word is initialized with zero before the call (constant INFCOMP in C language) for compression and to 4 (constant INFDECOMP in C language) for decompression.
-
input
Input area
Address of the input data to be compressed or decompressed depending on the function code.
-
insize
Length of the input area
This word (size int in C language) contains the length of the input area.
-
output
Output area
Depending on the function code, this area contains the address of the compressed or the decompressed data after the call.
-
outsize
Length of the output area
This word (size int in C language) indicates the required length of the output area and therefore must be initialized before the call. When returning control to the calling program, INFCMR00 places the actual length of the compressed or decompressed output into this field. If the length specified here was insufficient (i.e. the resultant compressed or decompressed data is sizeer than the output length that was specified), INFCMR00 fills the output area with the compressed or decompressed data up to the insufficient length and issues a return code (RETURN-CODE) of 4.
This function returns an entire value representing the return code of the compression or decompression.
The return code values are described below:
{wrapper="1" role="DL"}
-
0
step (compression or decompression) was performed
-
4
step incomplete, the output buffer is too small, the data are truncated
-
8
the value of the function parameter is incorrect
-
12
initial value of lengths for input or negative output or null or higher to SHRT_MAX (32767)
Description of the conversion macro
The function infcmr00 generates an optimal compression for the EBCDIC characters. In order to compress ASCII buffers, you should convert the ASCII string into an EBCDIC string before compression using the macro infxlt.
The macro infxlt uses the parameters described below:
{wrapper="1" role="DL"}
-
P1
pointer to buffer to be converted
-
P2
pointer to the conversion table (its length is 256)
-
P3
length of the buffer to be converted, maxi value INT_MAX (32767)
The INFOPAK.H file contains two parameter tables that can be used by the macro infxlt:
{wrapper="1" role="DL"}
-
TRUSEA
for the conversion EBCDIC to ASCII,
-
TRUSAE
for the conversion ASCII to EBCDIC.
You may modify these tables or use other tables.
Example with C language
/* Example C to use INFOPAK */
#include "INFOPAK.H"
{
/* Data for INFOPAK */
size int function , insize, outsize;
int returnInfopak ;
char input[100] , output[101] ;
. . .
/* translation ASCII to EBCDIC */
insize = 100 ; /* length to translate */
infxlt( input , trusae , insize ) ;
. . .
/* compression */
function = INFCOMP ;
outsize =101 ; /* length of output data */
returnInfopak = infcmr00( &function ,
input , &insize , output , &outsize ) ;
if ( returnInfopak != 0 )
printf("compression error") ;
. . .
/* decompression */
function = INFDECOMP ;
insize = outsize ; /* length reinitialization */
memcpy( input , output , insize ) ; /* and input area */
outsize = 101 ; /* length of output data */
returnInfopak = infcmr00( &function ,
input , &insize , output , &outsize ) ;
if ( returnInfopak != 0 )
printf("decompression error") ;
. . .
/* translation EBCDIC to ASCII */
infxlt( output , trusea , outsize ) ;
. . .
}
The example above performs the translation ASCII ---> EBCDIC, the compression of an area followed by the decompression and finally the translation EBCDIC ---> ASCII. In the decompression part, the length of the input area was re-initialized with the result provided by INFCMR00 (length of the compressed area) and the input area with the compressed data. The length of the output area is systematically initialized before the call takes place.
note
The length of the output area is one byte more than the length of the input area, thus ensuring that the length is sufficient for the compression. Indeed, when compression is impossible (random binary area), INFOPAK recopies the input area and adds one byte. If decompression takes place the original area is restored.