TELON to CICS Conversion

Introduction Conversion guidelines Call programs Maps/Screens Function keys Processing Attribute Handling Others Team Details

Introduction
CA-TELON, developed by "Computer Associates" is a productivity tool for the IBM Mainframe. It provides all facilities necessary to bring an application from the early stages of design through development and testing to full production and maintenance. It is used to develop Batch and Online programs easier and quicker than normal COBOL programming, as it involves a step-by-step process to build a complete application. The programmer simply provides information about the design of the program, rather than writing it in a higher-level language. TELON takes care of generating all the detailed syntax required by the language compiler. As TELON uses some standard procedures for developing COBOL codes, we need to find out some sort of guideline for converting an existing application form TELON to some other technology for re-engineering purposes. This document deals with the guidelines for TELON to CICS conversion. The main concern in this conversion procedures are inbuilt subroutines used by TELON, attribute handling, Screen processing and Function Key processing. You may require some additional guidelines for converting an existing application from TELON to CICS, which were beyond our project scope. Guidelines mentioned in this document are based on our project experience and existing application.

Conversion Guidelines
Please refer TELON ppt, to get a fundamental understanding of the flow of a TELON program. The section names given in TELON.ppt are generated in all TELON programs and are followed in the conversion guidelines as well.

Call Programs/Subroutines
Telon uses some in-built subroutines for standard validations e.g., date validations, character/integer validations etc. We need to replace these subroutines with the corresponding COBOL call programs or we may have to add extra code for these validations. Table 1.1 consists of some of the in-built subroutine with their description, which we faced in our project and require separate call programs. Other than these subroutines some routines dont require separate call programs, but the removal of those routines require slight modification to the code. These subroutines are ILALPHA and IFULLNUM. There may be some other subroutines available in Telon for which one need to analyze and find out the purpose of that particular subroutine. The conversions for in-built subroutines can be understood by following example: $$$$$$$$$$$$$$$$$----------------- OLD ----------------

CALL 'ODATE' USING

TPO-FROMDT TPO-FROMDT-LTH WORKFLD-NUMERIC. TPO-FROMDT TPO-FROMDT-LTH WORKFLD-NUMERIC.

$$$$$$$$$$$$$$$$$----------------- NEW ----------------

CALL 'XXXXX' USING

<------ Changed

Where XXXXX is the name of the newly coded call program. Remember to maintain the order of the parameters passed to linkage section. Note: - If the newly coded subroutine contains CICS statements then in that case you need to pass additional parameters DFHEIBLK and DFHCOMMAREA through linkage section of the program in following fashion.
$$$$$$$$$$$$$$$$$----------------- OLD ----------------

CALL 'OJULIAN' USING

TPO-LASTUPDT TPO-LASTUPDT-LTH WORKFLD-NUMERIC. DFHEIBLK DFHCOMMAREA TPO-LASTUPDT TPO-LASTUPDT-LTH WORKFLD-NUMERIC.

$$$$$$$$$$$$$$$$$----------------- NEW ----------------

CALL 'YYYYYYY' USING

Where YYYYYYY is the name of newly coded call program and assuming that the YYYYYYY contains the CICS statement.

Table 1.1
Description
Convert MMDDYY date to YYMMDD format Convert YYMMDD date to MMDDYY format Reformat floating point numbers Format the input data Format the output data Convert MM/DD/YY to YYDDD format Convert YYDDD to MM/DD/YY format Check if the string is numeric Check if the string contains characters only including special characters

Subroutine Name
IDATE ODATE IFLOAT IFORMAT OFORMAT IJULIAN OJULIAN INUMERIC IFULLCAR

For exact functionality of these call programs/subroutines refer the descriptions given below.

IDATE
Subroutine Overview: This subroutine validates the input date entered in mmddyy, mm/dd/yy and mm-ddyy format. After validation the date format is changed to yymmdd, yymmdd and mm/dd/yy respectively.

ODATE
Subroutine Overview: This subroutine converts dates from yymmdd format to mmddyy format if length passed is 6 and to mm/dd/yy format if length passed is 8.

IFLOAT
Subroutine Overview: This subroutine validates the input data and converts the data into the corresponding float format. The formatted data is sent back to the called program along with the indicator flag. The indicator flag will be spaces if there is no error in the input data other wise the flag will be having a value 'y'. The subroutine will return an error if the input data is Not numeric If the number of digits before the decimal point is greater than 11 If the number of digits after the decimal point is greater than 7

IFORMAT
Subroutine Overview: This subroutine formats and validates the input data. The subroutine removes all the special characters specified in the mask from the input data. The formatted data is sent back to the called program along with the indicator flag. The indicator flag will be spaces if there is no error in the input data other wise the flag will be having a value 'y'.

OFORMAT
Subroutine Overview: This subroutine formats and validates the input data. The subroutine inserts all the special characters specified in the mask to the output data. The formatted data is sent back to the called program.

IJULIAN
Subroutine Overview: This subroutine formats and validates the input date. The subroutine changes the format of the date from mm/dd/yy to Julian format yyddd. The formatted date is sent back to the called program.

OJULIAN
Subroutine Overview: This subroutine formats and validates the input date. The subroutine changes the format of the date from yyddd Julian format to mm/dd/yy format. The formatted date is sent back to the called program.

INUMERIC
Subroutine Overview: This subroutine validates the input data that is to check whether the user-entered data is numeric or not. The formatted data is sent back to the called program along with the indicator flag. The indicator flag will be spaces if there is no error in the input data other wise the flag will be having a value '0000'. The subroutine will return an error if the input data is

 Not numeric If the number of digits is greater than 11

IFULLCAR
Subroutine Overview: This subroutine validates the input data. If the input data is not spaces the subroutine checks for the presence of spaces in between the input data. If any embedded spaces are found in the input data the error indicator will be set to 'y'. Input data is sent back to the called program along with the indicator flag. The indicator flag will be spaces if there is no error in the input data other wise the flag will be having a value 'y'.

IFULLNUM
Subroutine Overview: For conversion of this subroutine we dont require any separate call program. We need to just modify the code in the following way wherever this subroutine is called: $$$$$$$$$$$$$$$$$----------------- OLD ---------------IF TPI-NACCTNUM NOT = SPACE CALL 'IFULLNUM' USING FIELD-EDIT-ERROR TPI-NACCTNUM-LTH TPI-NACCTNUM WORKFLD-NUMERIC

IF FIELD-EDIT-GOOD MOVE WORKFLD-NUMERIC TO WS-ACCOUNT-NUMBER $$$$$$$$$$$$$$$$$----------------- NEW ---------------IF TPI-NACCTNUM NOT = SPACE IF TPI-NACCTNUM IS NUMERIC MOVE TPI-NACCTNUM TO WS-ACCOUNT-NUMBER

ILALPHA
Subroutine Overview: For conversion of this subroutine we dont require any separate call program. Just delete these calls if the output is not used subsequently.
CALL 'ILALPHA' USING FIELD-EDIT-ERROR TPI-RECTYPE-LTH TPI-RECTYPE WORKFLD-ALPHA MOVE WORKFLD-ALPHA TO TPI-RECTYPE <--<--<--<--<--Delete Delete Delete Delete Delete

If the output of this call FIELD-EDIT-ERROR (or FIELD-EDIT-GOOD) is being used in the program after the call then change the code in following way: $$$$$$$$$$$$$$$$$----------------- OLD ---------------IF TPI-FINCO NOT = SPACE CALL 'ILALPHA' USING FIELD-EDIT-ERROR TPI-FINCO-LTH TPI-FINCO WORKFLD-ALPHA

IF FIELD-EDIT-GOOD MOVE WORKFLD-ALPHA TO DR01-LIFE-FINANCIAL-NO ELSE MOVE 'E' TO FIELD-INPUT-ERRORS MOVE ERROR-ATTR TO TPO-FINCO-ATTR $$$$$$$$$$$$$$$$$----------------- NEW ---------------IF TPI-FINCO NOT = SPACE MOVE TPI-FINCO TO DR01-LIFE-FINANCIAL-NO

TLRAINT and ADRASTG1

These subroutines require analysis based on project to project. Analyze the code behavior by removing calls to these subroutines. Along with these subroutines you may need to delete the whole Q-100-CICS-INIT SECTION and all calls to this section from the code. TOP

Maps/ Screen
The CICS Program uses the BMS maps for displaying and receiving data from terminal. It has two types of data fields: - Physical and symbolic. The physical field is one, which holds constant data like headings or data field names. The content cannot be modified during runtime. The symbolic field is one, which receives the user-entered data from screen or is used to hold program-generated data to display on screen. TELON uses predefined subroutine TLRATIO for sending the screen and receiving the screen in section C-100TERMIO-RECEIVE and section C-200TERMIO-WRITE in following way: C-100-TERMIO-RECEIVE.
CALL 'TLRATIO' USING DFHEIBLK DFHCOMMAREA CITATIO-READ TP-OUTPUT-TABLE

TP-OUTPUT-BUFFER-FIELDS TP-LITERAL-TABLE PFKEY-INDICATOR SCREEN-IMAGE-AREA SCREEN-IMAGE-END.

C-200-TERMIO-WRITE.
CALL 'TLRATIO' USING DFHEIBLK DFHCOMMAREA CITATIO-WRITE TP-OUTPUT-TABLE TP-OUTPUT-BUFFER-FIELDS TP-LITERAL-TABLE PFKEY-INDICATOR SCREEN-IMAGE-AREA SCREEN-IMAGE-END.

TLRATIO Subroutine passes the TP-OUTPUT-BUFFER-FIELDS while sending or receiving the screens. In conversion process we need to replace these TLRATIO calls with CICS maps receive and send commands in following way: $$$$$$$$$$$$$$$$$----------------- For receiving the map ---------------EXEC CICS IGNORE CONDITION MAPFAIL END-EXEC. EXEC CICS RECEIVE MAP ('XXXXXXXX') MAPSET ('YYYYYYYY') INTO (TP-BUFFER) END-EXEC. EXEC CICS HANDLE CONDITION MAPFAIL END-EXEC. MOVE EIBAID TO PFKEY-INDICATOR. $$$$$$$$$$$$$$$$$----------------- For sending the map ---------------EXEC CICS SEND MAP MAPSET FROM ERASE CURSOR END-EXEC. ('XXXXXXXX') ('YYYYYYYY') (TP-BUFFER)

Where XXXXXXXX and YYYYYYYY are map and mapset names. TLRATIO Subroutine also passes TP-LITERAL-TABLE as one of the parameters to the linkage section of the in-built subroutine. TP-LITERAL-TABLE is the collection of all the screen literals. As we are going to replace all the TELON screens with the respective CICS maps, we can directly delete TP-LITERAL-TABLE Section as it is going to be redundant after conversion. TLRATIO Subroutine also passes TP-OUTPUT-TABLE as one of the parameters. But we need to retain TP-OUTPUT-TABLE section, as we may need some of the length variables present in this section. For better understanding of this see the program overview of subroutine IDATE and ODATE. These subroutines require length of the field as one of the parameters passed to the linkage section.

Remove MOVE SCREEN-IMAGE TO TP-OUTPUT-BUFFER-FIELDS from code where error conditions are handled as follows: IF CLEAR MOVE DO-WRITE-LIT TO CONTROL-INDICATOR MOVE SCREEN-IMAGE TO TP-OUTPUT-BUFFER-FIELDS MOVE 'CLEAR IS NOT A VALID KEY' TO TPO-ERRMSG1 MOVE LOW-VALUES TO SCREEN-IMAGE-AREA GO TO P-100-PFKEYS-RETURN. <------delete

For generating the CICS maps from existing TELON screen definition given in Telon Panel Definition, we developed a REXX macro in our project. This REXX macro is available in knowledge shop. For accessing the macro click here. TOP

Function Keys
TELON and CICS both handle the operation related to PF keys in different ways. We will look that how they are handled and how we can change TELON PF key processing to equivalent CICS PF key processing.

TELON PF key handling: TELON uses an 88 level variable PFKEY-INDICATOR in System Work Area and PFKEY-RETURN-INDICATOR for PF key processing. While calling TLRATIO Subroutine TELON passes this PFKEY-INDICATOR variable and process accordingly with the help of PFKEY-RETURN-INDICATOR.
05 PFKEY-INDICATOR 88 ENTER-KEY VALUE 88 PA1 VALUE 92. 88 PFK1 VALUE 1. 88 PFK4 VALUE 4. 88 PFK7 VALUE 7. 88 PFK10 VALUE 10. 88 PFK13 VALUE 13. 88 PFK16 VALUE 16. 88 PFK19 VALUE 19. 88 PFK22 VALUE 22. 88 PFK1-13 VALUE 88 PFK3-15 VALUE 88 PFK5-17 VALUE PIC 99. 88 CLEAR VALUE 93. PA2 VALUE 94. 88 PA3 VALUE 91. PFK2 VALUE 2. 88 PFK3 VALUE 3. PFK5 VALUE 5. 88 PFK6 VALUE 6. PFK8 VALUE 8. 88 PFK9 VALUE 9. PFK11 VALUE 11. 88 PFK12 VALUE 12. PFK14 VALUE 14. 88 PFK15 VALUE 15. PFK17 VALUE 17. 88 PFK18 VALUE 18. PFK20 VALUE 20. 88 PFK21 VALUE 21. PFK23 VALUE 23. 88 PFK24 VALUE 24. 13. 88 PFK2-14 VALUE 2 14. 15. 88 PFK4-16 VALUE 4 16. 17. 88 PFK6-18 VALUE 6 18.

0. 88 88 88 88 88 88 88 88 88 1 3 5

88 PFK7-19 88 PFK9-21 88 PFK11-23

VALUE 7 19. VALUE 9 21. VALUE 11 23.

88 PFK8-20 88 PFK10-22 88 PFK12-24

VALUE 8 20. VALUE 10 22. VALUE 12 24.

CICS PF key handling: CICS uses a standard copybook DFHAID for PF key handling and just after receiving the map we can evaluate EIBAID for recognizing the PF key pressed. For conversion from TELON to CICS we require a mapping between PFKEYINDICATOR variable available in TELON and DFHAID copybook in CICS. We can replace this 88 level PFKEY-INDICATOR variable with a separate standard copybook (note that we are not going to make use of DFHAID, we are just creating new mapping). In this conversion process we will still make use of PFKEY-RETURN-INDICATOR variable with the new mapping. For new mapping click here. With this add following line after receiving the map. MOVE EIBAID TO PFKEY-INDICATOR. Note: - Along with this new mapping look for code similar to following in TELON code
IF PFKEY-INDICATOR EQUAL 08 OR 20 MOVE '1' TO PAGE-REQUEST-INDICATOR

We also need to change this type of code with following code: IF PFK8-20 MOVE '1' TO PAGE-REQUEST-INDICATOR

Explanation: - PFKEY-INDICATOR variable used in TELON is Pic 99 variable hence it contains only numeric values while all the components of DFHAID copybook are of type Pic X and these can hold alphanumeric values. Our new copybook mapping also have variable PFKEY-INDICATOR of type Pic X. So the checks of this kind going to fail after conversion. Because of this we need to check the 88 level variables instead of higher level variable PFKEY-INDICATOR, which is using EQUAL clause. TOP

Attribute
TELON and CICS handle various attribute settings like protect/unprotect fields, making fields normal/bright/dark, setting the cursor position etc. in different ways. We shall look at how TELON processes attributes and how we can change TELON attribute processing to equivalent CICS attribute processing.

TELON attribute handling: TELON uses a variable called ATTRIBUTE-VARIABLES in System Work Area for setting attribute properties and for cursor positioning. TELON also generates attribute variables to control how the fields will be displayed. The attribute name for each field on the screen takes the form TPO-<fldname>-ATTR. Screen fields are displayed and controlled using the attribute fields as described below. By moving the following '-ATTR's to the TPO-<fldname>-ATTR variable, individual fields can be controlled.
CURSOR-ATTR ERROR-ATTR

Position Cursor on the field (value ' {' or FFFFC0).

Position Cursor on and highlight the field at the same time (value ' H' or FFFFC8). This is the default attribute and causes the field to be unprotected, normal intensity etc. (value ' {' or 0000C0).
OK-ATTR PROT-ATTR

Protect the screen field (value ' 0' or 0000F0). Protect the screen field (value ' 0' or 0000F0).

OUTPUT-ATTR

Protect the field and blank it out at the same time (value ' ' or 0000FC).
OUTPUT-BLANK-ATTR BLANK-ATTR

Protect the field and blank it out at the same time (value ' '

or 0000FC). Position the cursor on the field and blank it out at the same time (value ' ' or FFFFCC).
CURSOR-BLANK-ATTR INPUT-BLANK-ATTR OUTPUT-HIGH-ATTR

Blank the field (value ' ' or 0000CC). Protect and highlight the field at the same time

(value ' 8' or 0000F8).

INPUT-HIGH-ATTR

Highlight the field (value ' H' or 0000C8).

An example using these attributes could be: MOVE CURSOR-ATTR

TO TPOEMPNO-ATTR.

CICS attribute handling: In CICS we have copybook DFHBMSCA included for setting the attribute properties. For conversion from TELON to CICS we need to replace the variable ATTRIBUTEVARIABLES with corresponding CICS compatible attributes. For this delete the ATTRIBUTE-VARIABLES from system work area and replace this with the copybook containing CICS compatible attributes. For accessing copybook remapped for this conversion process click here. Along with the inclusion of this copybook change the movement of attributes according to the new copybook mapping given in Table 1.2. By looking at Table 1.2 you can see that we are using TPO-XXXXXX-LEN variables for cursor positioning, which are not a part of existing TELON code. Hence for incorporating these variables we need to change variables present in TP-BUFFER section in following manner: $$$$$$$$$$$$$$$$$----------------- OLD ---------------05 TPO-PROGRAM-ATTR PIC XXX. 05 TPO-PROGRAM PIC X(8). $$$$$$$$$$$$$$$$$-------------------------------------$$$$$$$$$$$$$$$$$----------------- NEW ---------------05 TPO-PROGRAM-LEN PIC S9(4) COMP. 05 TPO-PROGRAM-ATTR PIC X. 05 TPO-PROGRAM PIC X(8). $$$$$$$$$$$$$$$$$-------------------------------------<---- Added <---- Changed

Mapping of TELON attributes with the equivalent CICS attributes Table 1.2
TELON Attribute
BLANK-ATTR CURSOR-ATTR CURSOR-BLANK-ATTR ERROR-ATTR INPUT-BLANK-ATTR INPUT-HIGH-ATTR OK-ATTR OUTPUT-ATTR OUTPUT-BLANK-ATTR

Old TELON Attribute Statement

MOVE BLANK-ATTR TO TPO-XXXXXXX-ATTR MOVE CURSOR-ATTR TO TPO-XXXXXXX-ATTR MOVE CURSOR-BLANK-ATTR TO TPO-XXXXXXX-ATTR MOVE ERROR-ATTR TO TPO-XXXXXXX-ATTR MOVE INPUT-BLANK-ATTR TO TPO-XXXXXXX-ATTR MOVE INPUT-HIGH-ATTR TO TPO-XXXXXXX-ATTR MOVE OK-ATTR TO TPO-XXXXXXX-ATTR MOVE OUTPUT-ATTR TO TPO-XXXXXXX-ATTR MOVE OUTPUT-BLANK-ATTR TO TPO-XXXXXXX-ATTR

New CICS Equivalent Statement

MOVE PROT-MDTON-DRK TO TPO-XXXXXXX-ATTR MOVE -1 TO TPO-XXXXXXX-LEN MOVE UNPROT-MDTON-LI TO TPO-XXXXXXX-ATTR MOVE -1 TO TPO-XXXXXXX-LEN MOVE UNPROT-MDTON-DRK TO TPO-XXXXXXX-ATTR MOVE -1 TO TPO-XXXXXXX-LEN MOVE UNPROT-MDTON-HI TO TPO-XXXXXXX-ATTR MOVE UNPROT-MDTON-DRK TO TPO-XXXXXXX-ATTR MOVE UNPROT-MDTON-HI TO TPO-XXXXXXX-ATTR MOVE UNPROT-MDTON-LI TO TPO-XXXXXXX-ATTR MOVE PROT-MDTON-LI TO TPO-XXXXXXX-ATTR MOVE PROT-MDTON-DRK TO TPO-XXXXXXX-ATTR

OUTPUT-HIGH-ATTR PROT-ATTR

MOVE OUTPUT-HIGH-ATTR TO TPO-XXXXXXX-ATTR MOVE PROT-ATTR TO TPO-XXXXXXX-ATTR

MOVE PROT-MDTON-HI TO TPO-XXXXXXX-ATTR MOVE PROT-MDTON-LI TO TPO-XXXXXXX-ATTR

TOP

Others
Comments: - As TELON uses a step-by-step process to build a complete application, it
uses some standard comments for explaining the working of code. Some of these comments may become redundant after the conversion. So you can delete these comments or you can just modify them according to your needs. Some of the guidelines for conversion of comments are as follows: You may find out the comments to be changed by giving a search for TELON or T E L O N in the code. Remove all the lines containing skip, skip1, skip2, skip3, skip4, skip5 and eject. Add comment in modification log mentioning your project code and description of the same. Remove or modify the lines containing strings GENERATED , COPY CODE and SCREEN/ according to your judgment as these lines are generated by TELON for explaining the code.

Copybooks: - Telon uses some standard copybooks to avoid repetition of code e.g. for
PF keys processing etc. When we generate the COBOL code from TELON code these copybooks get expanded in the code. These copybooks may be of two types: TELON generated copybooks Application specific copybooks generated by the user For TELON generated copybooks just remove the header and footer of these copybooks in following manner: *TELON-------------------------------------------------------------<--Delete *DS: H04 | COPY LADFACLR | <--- Delete *-----------------------------------------------------------------<--- Delete IF CLEAR | MOVE 'LDDPACAB' TO NEXT-PROGRAM-NAME | EXEC CICS XCTL PROGRAM(NEXT-PROGRAM-NAME) |

COMMAREA(SPA-AREA) | LENGTH(SPA-LENGTH) | END-EXEC. | *----------------------------------------------| ---<--- Delete END LADFACLR

For production copybooks specific to programs delete the whole copybook and replace this with COPY command in COBOL in following way: *TELON-----------------------------------------------------------<--- Delete *DS: PXDB0000.RECLIB | COPY LTWKAREA | <--- Delete

*---------------------------------------------------------------------------<--- Delete ***************************************************************** * | <--- Delete * L T W K A R E A * | <--- Delete * CORRESPONDENCE INFORMATION * | <--- Delete ***************************************************************** * | <--- Delete * | <--- Delete 01 WORKAREA. | <--- Delete * STANDARD ERROR MESSAGE DATA ITEMS REQUIRED BY ALL SYSTEMS | <--- Delete 05 ERROR-MESSAGE-NOHIT PIC X(28) | <--- Delete VALUE '*** NO OPTION SELECTED ***'. | <--- Delete 05 ERROR-MESSAGE-MULTHIT PIC X(37) | <--- Delete VALUE '*** MORE THAN ONE OPTION SELECTED ***'. | <--- Delete 05 ERROR-MESSAGE-HIGHLIGHT PIC X(40) <--- Delete VALUE '** ABOVE HIGHLIGHTED FIELDS IN ERROR **'. | <--- Delete ***************************************************************** | <--- Delete * END OF MEMBER LTWKAREA | <--- Delete ***************************************************************** | <--- Delete *----------------------------------------------| END LTWKAREA ---<--- Delete

And replace this with the following statement, but keep in mind that this copybook should present in the production library (in this case PXDB0000.RECLIB) and include this library in your compile JCL.
COPY LTWKAREA.

 Remove TELON-RELEASE-DATA Section fully as it contains the variable, which holds information regarding the date and time when the TELON source got generated. As in conversion process we dont want this information we can directly remove this section. Tip: - All these changes to the code can be easily automated with the help of text pad macro. If you dont how to record macros in text pad click here for demo. TOP

Team Details
Following are the mail ids of the people with their roles, who were involved in the developing these guidelines for conversion process. For any clarification you can contact any one of these: Project Leader: - Elamurugan_vs, Pradeep_k Configuration Controller: - Saravanan_ganesan Onsite Coordinator: - Leof_thangaraj Developers: - Aneeshazeez_manzil, Anoopp_v, Anuj_Rastogi, Anupam_Bansal, Ashok_Kalidasan, Arun_Bhatt, Ganesh_Hariharan, Jayant_devanathan, Rockey_Nebhwani For issues related to Call Programs: - Aneeshazeez_manzil, Anoopp_v, Ashok_Kalidasan For any other document related to this project like Impact Analysis Document, Sample Unit Test Plan, Integration Test Plan you can access the process assets of JCPDMS3C.