Character Data Representation Architecture

Appendix I. DFSMS/MVS Considerations

CDRA API Considerations for DFSMS/MVS

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:

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.

Figure 103. Sample C routine

Show Figure 103. Sample C routine | Hide Figure 103. Sample C routine

#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("Sucessfully initialize multiple-step conversion.\n"); else { printf("Unsucessfully 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("Sucessfully perfom multiple-step conversion.\n"); printf("OUTSTREAM=%s\n",outstring); } CDRMSCC((long int *)&Token, /* handle */ &FeedBack); /* feed back */ if(!FeedBack.Status && !FeedBack.Reason) printf("Sucessfully clean up multiple-step conversion.\n"); else printf("Unsucessfully clean up multiple-step conversion.\n");

}

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.

Figure 104. Sample COBOL routine

Show Figure 104. Sample COBOL routine | Hide Figure 104. Sample COBOL routine

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.

CDRA APIs in the DFSMS/MVS Product

The following CDRA APIs are included in the DFSMS/MVS product library:

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

Contact IBM

Need assistance with your globalization questions?