|
This appendix provides additional information necessary to install and use
the CDRA APIs included in the DFSMS/MVS product. APIs are found in "Chapter
5. CDRA Interface Definitions"; they are not duplicated in this appendix.
The CDRA support provided will function in the following environments:
- DFSMS/MVS 1.3.0
- All levels of MVS/SP that are consistent with DFSMS 1.3.0, which are currently
MVS/ESA 4.3, 5.1 and 5.2.
- The Language Environment/370 (LE/370) must be available for both the installation
and execution of the CDRA services code.
With MVS/ESA SP 5.2 or higher, these requirements are met if the C/C++ Language
support feature of MVS/ESA SP or the LE for MVS and VM program
product is used.
With MVS/ESA SP 5.1, these requirements are met if the C/C++ Language support
feature of MVS/ESA SP or the LE/370 program product is used.
With MVS/ESA SP 4.3, these requirements are met if the LE/370
program product is used.
Completing the Character Conversion Services
Installation
Tailor the CDRAINIT member of SYS1.SAMPLIB as required by your installation,
then run it to define the work data sets used by the various conversion routines.
The following data sets will be created as a result of running the CDRAINIT
member:
- SYS1.CDRASRVT
- The code page resource tables
- SYS1.CDRSRVCI
- An index over the SYS1.CDRSRVCR data set
- SYS1.CDRSRVCR
- The CCSID resource table
- SYS1.CDRSRVGR
- The GCCST resource table
These data sets will occupy approximately 350 tracks of 33xx-type direct access
storage.
API Tracing
API tracing can be performed by coding a DD statement for CDRATRC in the job
control language for job steps invoking CDRA services. The trace statement can
be entered as follows:
//CDRATRC DD SYSOUT=*
Application Programming Considerations
The application program must ensure that the appropriate Language Environment
run time environment is enabled prior to calling any of the CDRA based services.
If CDRA is invoked without having performed the recommended installation process
that linkedits the CDRA component with SYS1.SCEELKED, the result
will be an error with a status code of 2048 and a reason code of 2, when the
CDRA component attempts to call a C runtime function. For more information on
the Language Environment, please see the Language Environment Programming Guide,
SC26-4818.
The calling application program may or may not be APF authorized and can be
running in any non-zero protect key. The calling program must be AMODE(31) and
must be in TCB mode.
The CDRA services have been implemented using the C programming language, but
the functions themselves can be called in a language independent manner from
any high level programming language.
Two programming examples are provided to show how an application program can
call the CDRA services. For applications written using AD/CYCLE C, the CDRA
services can be accessed in the same manner as other C functions are called,
as shown in Figure 103. COBOL based applications can
invoke the CDRA services as shown in the COBOL programming example Figure
104. PL/I based applications can similarly invoke CDRA services.
Sample C Routine
This routine demonstrates how to call the DFSMS/MVS CDRA services to perform
the multistep character data conversion using the C programming language.
#pragma runopts(STACK(16K,4K,BELOW),HEAP(64K,4K,BELOW))
#pragma title("CDRATEST")
#pragma options(RENT)
#pragma strings(readonly)
#pragma csect(code, "CDRATEST")
#pragma csect(static, "#CDRATST")
/*#pragma string(WRITABLE)*/
#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <ctype.h>
#include <string.h>
/* Definitions required to call CDRA APIs */
typedef long CDRASRV_CCSID_T;
typedef struct { /* structure used to return a return code */
short Status;
short Reason;
long reserved1;
long reserved2;
} CDRASRV_FeedBack_T;
void CDRMSCI(const CDRASRV_CCSID_T * ccsid1,
const long * StringType1,
const CDRASRV_CCSID_T * ccsid2,
const long * StringType2,
const long * gccasn,
long * Token,
CDRASRV_FeedBack_T * FeedBack);
void CDRMSCP(const long * Token,
const char * String1,
const long * Length1,
const long * Length2,
char * String2,
long * OutLength,
long * ErrorByteNr,
CDRASRV_FeedBack_T * FeedBack);
void CDRMSCC( long * Token,
CDRASRV_FeedBack_T * FeedBack);
main(int argc, char* argv[])
{
const long inputST = 0; /* type of input string */
const long outputST = 1; /* type of input string */
const long cnvGCCASN = 0; /* conversion alternative */
const long lL1 = 26;
const long lL2 = 160;
int RecDataLen, /* Record Length */
NumRecs, /* Number of Records */
RC1,RC2; /* Return Code */
int RecRtnCnt, /* record return count */
RecordLen; /* record length */
long int Token[8]; /* CDRA token */
char instring [80];
char outstring [160];
long inputCCSID, /* input CCSID */
outputCCSID; /* output CCSID*/
CDRASRV_FeedBack_T FeedBack; /* feed back area */
int long lL3,lL4; /* string length */
printf(" program starting \n");
memcpy(instring,"ABCEDFGHIJKLMNOPQRSTUVWXYZ",26);
inputCCSID = 500;
outputCCSID = 437;
CDRMSCI(&inputCCSID, /* EBCDIC codepage */
&inputST, /* graphic char with length specify */
&outputCCSID, /* ASCII codepage */
&outputST, /* graphic char with length specify */
&cnvGCCASN, /* installation default */
(long int *)&Token, /* handle */
&FeedBack); /* feed back */
if(!FeedBack.Status && !FeedBack.Reason)
printf("Successfully initialize multiple-step conversion.\n");
else {
printf("Unsuccessfully initialize multiple-step conversion.\n");
printf("Status: %d, Reason: %d\n",FeedBack.Status,FeedBack.Reason);
return(1);
}
CDRMSCP((long int *)&Token, /* handle */
instring, /* string to be converted */
&lL1, /* input string length */
&lL2, /* output string length */
outstring, /* result string */
&lL3, /* result string length */
&lL4, /* result string error */
&FeedBack); /* feed back */
if(!FeedBack.Status && !FeedBack.Reason) {
printf("Successfully perform multiple-step conversion.\n");
printf("OUTSTREAM=%s\n",outstring);
}
CDRMSCC((long int *)&Token, /* handle */
&FeedBack); /* feed back */
if(!FeedBack.Status && !FeedBack.Reason)
printf("Successfully clean up multiple-step conversion.\n");
else
printf("Unsuccessfully clean up multiple-step conversion.\n");
}
|
Figure 103. Sample C routine
Sample COBOL Routine
This example shows how to call the DFSMS/MVS CDRA services to initialize, perform
data conversion on a character string, and cleanup, using the COBOL programming
language.
|
IDENTIFICATION DIVISION.
PROGRAM-ID. CDRA.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CCSID1 PIC 9(9) COMP VALUE 500.
01 STRTYP1 PIC 9(9) COMP VALUE 0.
01 CCSID2 PIC 9(9) COMP VALUE 437.
01 STRTYP2 PIC 9(9) COMP VALUE 0.
01 GCCASN PIC 9(9) COMP VALUE 0.
01 INSTR PIC X(26) VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
01 OUTSTR PIC X(26) VALUE " ".
01 STRLL1 PIC 9(9) COMP VALUE 26.
01 STRLL2 PIC 9(9) COMP VALUE 26.
01 STRLL3 PIC 9(9) COMP VALUE 0 .
01 STRLL4 PIC 9(9) COMP VALUE 0 .
01 TOKEN.
05 V OCCURS 8 TIMES.
10 V1 PIC 9(4) .
01 FB1 PIC 9(16) COMP.
01 FB2.
02 STAT PIC 9(4) COMP.
02 REASON PIC 9(4) COMP.
02 RES1 PIC 9(4) COMP.
02 RES2 PIC 9(4) COMP.
PROCEDURE DIVISION.
CALL "CDRMSCI" USING CCSID1, STRTYP1, CCSID2, STRTYP2,
GCCASN, TOKEN, FB2.
DISPLAY FB2 .
DISPLAY "RESULT" STAT, REASON.
CALL "CDRMSCP" USING TOKEN, INSTR, STRLL1, STRLL2,
OUTSTR, STRLL3, STRLL4, FB2.
DISPLAY "RESULT" STAT, REASON.
DISPLAY OUTSTR .
CALL "CDRMSCC" USING TOKEN, FB2.
DISPLAY "RESULT" STAT, REASON.
STOP RUN.
|
Figure 104. Sample COBOL routine
|
|
The following CDRA APIs are included in the DFSMS/MVS product library:
- Get Encoding Scheme, Character Set, and Code Page Elements (CDRGESP)
- Get Short Form (CCSID) from Specified ES (CS, CP) (CDRSCSP)
- Get Encoding Scheme Element and its Subelements (CDRGESE)
- Get Control Function Definition (CDRGCTL)
- Get Short Form (CCSID) with Maximal CS for Specified ES, CP (CDRSMXC)
- Multiple-Step Convert Initialize (CDRMSCI)
- Multiple-Step Convert Perform (CDRMSCP)
- Multiple-Step Convert Clean Up (CDRMSCC)
- Extract Status and Reason Codes from Feedback Code (CDRXSRF)
CDRGESP - Get Encoding Scheme, Character
Set, and Code Page Elements API
The following parameter ranges and functional differences apply when using
the CDRGESP API (as described in "CDRGESP - Get Encoding
Scheme, Character Set, and Code Page Elements") with the DFSMS/MVS product.
- GESP parameter difference
- none
CDRSCSP - Get Short Form (CCSID) from
Specified ES (CS, CP) API
The following parameter ranges and functional differences apply when using
the CDRSCSP API (as described in "CDRSCSP - Get Short Form
(CCSID) from Specified ES (CS, CP)") with the DFSMS/MVS product.
- SCSP parameter difference
- none
CDRGESE - Get Encoding Scheme Element
and its Subelements API
The following parameter ranges and functional differences apply when using
the CDRGESE API (as described in "CDRGESE - Get Encoding
Scheme Element and its Subelements") with the DFSMS/MVS product.
- GESE parameter difference
- none
CDRGCTL - Get Control Function Definition
API
The following parameter ranges and functional differences apply when using
the CDRGCTL API (as described in "CDRGCTL - Get Control
Function Definition") with the DFSMS/MVS product.
- GCTL parameter difference
- none
CDRSMXC - Get Short Form (CCSID) with
Maximal CS for Specified ES, CP API
The following parameter ranges and functional differences apply when using
the CDRSMXC API (as described in "CDRSMXC - Get Short Form
(CCSID) with Maximal CS for Specified ES, CP") with the DFSMS/MVS product.
- SMXC parameter difference
- none
CDRMSCI - Multiple-Step Convert Initialize
API
The following parameter ranges and functional differences apply when using
the CDRMSCI API (as described in "CDRMSCI - Multiple-Step
Convert Initialize") with the DFSMS/MVS product.
- MSCI parameter difference
- only values of 0 or 1 are supported and BOTH of these values will
provide the IBM defined defaults. The value 0 is used to select the designated
installation default conversion method and tables. The value
of 1 is used to select the CDRA-defined default method and conversion
tables .
CDRMSCP - Multiple-Step Convert Perform
API
The following parameter ranges and functional differences apply when using
the CDRMSCP API (as described in "CDRMSCP - Multiple-Step
Convert Perform") with the DFSMS/MVS product.
- MSCP parameter difference
- none
CDRMSCC - Multiple-Step Convert Clean
Up API
The following parameter ranges and functional differences apply when using
the CDRMSCC API (as described in "CDRMSCC - Multiple-Step
Convert Clean Up") with the DFSMS/MVS product.
- MSCC parameter difference
- none
CDRXSRF - Extract Status and Reason Codes
from Feedback Code API
The following parameter ranges and functional differences apply when using
the CDRXSRF API (as described in "CDRXSRF - Extract Status
and Reason Codes from Feedback Code") with the DFSMS/MVS product.
- XSRF parameter difference
- none
|
