IBM Books

Migrating to VisualAge Generator


Appendix B. Migrating from Cross System Product Interpretive to COBOL

This section lists considerations that apply when migrating from CSP/AE to VisualGen Host Services(including VisualGen Host Services for OS/400).


Member Names

The following are considerations for member names:


Language Element Compatibility Considerations

The following gives an overview of the compatibility considerations for language elements. The language elements include the following:

Mapping Support

Migration considerations for mapping support are as follows:

CONVERSE Process Option

Migration considerations for the CONVERSE process option are as follows:

EZE Special Function Words

Migration considerations for EZE special function words are as follows:

Transferring Among Applications

Migration considerations for transferring among applications are as follows:

File Support

Migration considerations for file and database support are as follows:

Relational Database (SQL) Support

Migration considerations for SQL applications are as follows:

DL/I Database Support

Migration considerations for DL/I applications are as follows:

Data Values

Migration considerations for data values are as follows:

User Message Files

Migration considerations for user message files are as follows:

Language-Dependent Variables

Under CSP/AD 3.3 and CSP/AE 3.3, message 1 was used to indicate the language-dependent variables (YES/NO response, currency symbol, numeric separator, and SQL indicators). With VisualGen Host Services, the language-dependent variables are in a language-dependent installation module. You can customize the module when you install VisualGen Host Services. For MVS or VSE, refer to the VisualGen Host Services program directory or the Running VisualGen Applications on MVS and Running VisualGen Applications on VSE documents for additional information about setting the language defaults for your installation. For VM, refer to the VisualGen Host Services program directory.

CSP/AD Language Elements Associated with the Application Load File

CSP/AD language elements associated with the CSP/AE load modules in the ALF are not supported.


Application Storage Requirements

The application storage requirements function of CSP/AD 3.3 and earlier releases reported the size of CSP/AE application load modules in the ALF. This function is not required with VisualGen Host Services because the load modules are standard COBOL.

Because an application has become a standard COBOL load module, when an application is running, it now is loaded into memory instead of being read into GETMAIN storage. This means that the residency of the application is controlled by the target environment.

In ESA systems for MVS CICS and VSE CICS, by default, the load modules are loaded above the 16MB line. In MVS CICS and VSE CICS, the load modules remain in storage until the region is shut down, regardless of whether the modules are marked as resident, because these releases of CICS do not perform program compression above the 16MB line. Depending on the size of your applications, the number of applications you have, and the size of your region, you could receive an insufficient storage condition. Therefore, you should ensure that your "above the line" region is large enough to contain the load modules used over the life of a region, or link all the applications to run below the 16MB line.

In CICS/ESA, this problem does not exist.

In VM/ESA, the storage needed by the application plus the storage needed for VisualGen Host Services determines the virtual machine size needed to run a VisualGen Host Services application. Because VisualGen Host Services dynamically loads some of the modules it uses, it is difficult to determine exactly how much storage is needed for a particular application.

A virtual machine size of 20MB (megabytes) is recommended for generating and running applications using VisualGen Host Services, and is necessary if the user wants the VisualGen Host Services code to run above the 16MB line. Running VisualGen Host Services above the 16MB line allows more room for VisualAge Generator applications below the 16MB line. The virtual machine size required to generate a VisualGen Host Services application has several dependencies, including the following:


Coexistence with CSP/AE Applications

The applications, map groups, and tables managed by CSP/AE are not the same objects created by generating VisualAge Generator applications, map groups, and tables.

CSP/AE applications and generated COBOL applications can coexist on the same system. However, generated COBOL applications look like non-Cross System Product programs to CSP/AE. Therefore, to avoid inconsistent operating results, it is better to convert all applications that run together in the same transaction, job step, or MVS/TSO or VM invocation from CSP/AE run time to COBOL run time at the same time. Operating inconsistencies occur on partial conversions from CSP/AE to COBOL run time in sets of interacting applications with the following characteristics:

If the above characteristics do not apply in your situation, generated COBOL applications can interface with CSP/AE applications in the same way the non-Cross System Product programs interface with CSP/AE applications.

CSP/AE can call a generated COBOL application if that called application has been generated with default linkage and the called application is not found in the CSP/AE ALF.

A generated COBOL application can call a CSP/AE application only through a bridge program. The bridge program expects a generated COBOL linkage and calls CSP/AE as defined in the CSP/AE 3.3 (or earlier) documentation for calls from a non-Cross System Product program to a CSP/AE application. There is no COBOL linkage table entry that directly generates a call to CSP/AE applications.

Non-Cross System Product programs that currently call or transfer to CSP/AE applications must be modified if the CSP/AE applications are generated again as COBOL. The modifications include calling or transferring directly to the generated COBOL application instead of starting up the CSP/AE interpreter and passing the name of the application to be run as a parameter. Refer to the Developing VisualAge Generator Client/Server Applications document for a detailed description of the interface to applications generated with the VisualAge Generator application generation facility.

A CSP/AE application can coexist on the same system with the same application generated as a COBOL program. This allows called applications to be installed for use with both CSP/AE applications and generated COBOL applications.

If CSP/AE applications use a table or map group that is also generated as a VisualAge Generator table or map group, the CSP/AE applications do not share the table or map group with generated COBOL applications.

For OS/400 coexistence restrictions, refer to the Running VisualAge Generator Applications on OS/400 document.


Transferring Control in the CICS Environment

For the CICS environment, the X'FFFFFFFF' fullword at the end of the parameter list is consistent with the CSP/AE CALL interface. The length of the COMMAREA does not include this fullword unless /ENDCOMMAREA is specified as a COBOL generation option for the calling application. If the generation option /ENDCOMMAREA was specified and the parameter format COMMPTR is in effect, the length specified for COMMAREA on the EXEC CICS LINK command is automatically increased by 4 bytes. Under certain conditions, CICS passes a copy of the COMMAREA to the called application. Specify /ENDCOMMAREA to ensure that the X'FFFFFFFF' fullword is included when a copy of the COMMAREA is made.


MVS CICS and VSE CICS Resource Table Requirements for Applications

To install generated applications for MVS CICS and VSE CICS, all main transaction, main batch, dynamically called applications, print services programs, map group format modules, and table programs must have an entry in the PPT (or the RDO equivalent). To start each application by entering a transaction code started from MVS CICS and VSE CICS, or with XFER, CREATX, or EZESEGTR as the result of a segmented converse, each application must have a unique transaction ID assigned and have an entry in the PCT (or the RDO equivalent). Specify /CICSENTRIES=RDO as a generation option if you want to generate model resource definition online (RDO) program and transaction definitions. Specify /CICSENTRIES=MACRO as a generation option if you want to generate model PPT and PCT table entries.

Refer to the Running Applications on MVS and Running Applications on VSE documents for additional information on installing generated applications.


MVS CICS and VSE CICS Table Entries for Host Services

If you previously installed CSP/AE and plan to run CSP/AE and VisualGen Host Servicesin the same MVS CICS or VSE CICS region, you need to make the following modifications to your MVS CICS or VSE CICS tables and JCL:


National Language Codes

The NLS code has been extended to 3 characters. The first two characters define the base language (for example, EN is for English). The third character can either represent natural continuation or identifies variation, script, or dialect. The NLS codes are as follows:

Table 6. Language Support Suffixes
Description V3.3 VisualAge Generator
Default language D See note.
U.S. English (Mixed case English) E ENU
Uppercase English U ENP
Simplified Chinese C CHS
German (Germany) G DEU
German (Switzerland) W DES
Japanese J JPN
Korean K KOR
Portuguese (Brazilian) P PTB
Note:The default language is specified as an installation option. A unique code for the default language is no longer required.


CSP/AE Invocation Parameters

CSP/AE invocation parameters have been replaced with generation options, installation options, or are no longer supported. The invocation parameter group file is still used by the FZETPRT utility program.

Table 7 shows how MVS CICS invocation parameters are supported when using generated COBOL applications.

Table 7. Invocation Parameter Migration for MVS CICS
Parameter Corresponding Function in VisualAge Generator
P=yyyy The application developer can specify an alternate transient data or spool file during generation by using a resource association file. The application can dynamically change the target transient data queue name or JES spool file name by using the special word EZEDESTP.
NLS=n The NLS code for VisualGen Host Services is specified at generation time with the /TARGNLS generation option.
SEG The application switches between segmented and nonsegmented mode by setting EZESEGM.
DMODE=S|D|A You choose whether DB2 or ANSI SQL statements are generated using the /ANSISQL generation option. DB2 SQL statements or ANSI SQL statements are imbedded directly into the generated COBOL application. DMODE=D (dynamic execution without an application specific BIND) is not supported.
RT=zzzz The RT option is specified at generation time through the /RT generation option. The application user no longer has to press attention interrupt to go on to the next transaction; the transaction is started automatically.
TSMS The /WORKDB generation option specifies whether auxiliary or main temporary storage is used for saving working storage across segments.
NOTXA Use the /DATA=24 generation option to force all working storage to be acquired below the line.
IMSESA The IMSESA setting is controlled by the installation options module.
FFFF The /MARKLISTEND generation option specifies whether the end of list indicator is used.
PARMS=xxxxxxxx Invocation Parameter Group name is not supported.

In the MVS/TSO environment, a generated main transaction or main batch program is invoked by a CLIST. A sample CLIST specifically for the application is created by the COBOL generator if the /RUNFILE option is specified. The CLIST might need to be modified to add data set ALLOCATE commands for data sets required by called or transferred-to applications or for data sets accessed by setting the EZEDEST or EZEDESTP special function word.

Table 8 shows how MVS/TSO invocation parameters are supported when using generated COBOL applications.

Table 8. Invocation Parameter Migration for MVS/TSO
Parameter Corresponding Function in VisualAge Generator
NLS(n) The NLS code for VisualGen Host Services is specified at generation time with the /TARGNLS generation option.
DSYS(ssss) The DB2 subsystem is specified in the CLIST. The application developer can modify the generated CLIST to change the DB2 subsystem used with the application. The system administrator could also modify the CLIST template to set the default DB2 subsystem ID to the subsystem that is normally used.
PSB(pppppppp) The PSB name is specified in the CLIST. The name defaults to the name of the application PSB member name. The application developer can modify the generated CLIST to change the PSB value specified for the application. The system administrator could also modify the CLIST template to set the default PSB name generated in the CLIST to be the application name instead of the application PSB member name.
BKO(xxx) The BKO value is specified in the CLIST. The application developer can modify the generated CLIST to change the BKO value specified for the application. The system administrator could also modify the CLIST template to change the BKO value specified for the application.
DMODE=S|D|A You choose whether DB2 or ANSI SQL statements are generated using the /ANSISQL generation option. DB2 SQL statements or ANSI SQL statements are imbedded directly into the generated COBOL application. DMODE=D (dynamic execution without an application specific BIND) is not supported.
DPLAN(pppppppp) The DB2 plan name is specified in the CLIST. The default plan name is the application name. The application developer can modify the generated CLIST to change the DB2 plan used with the application.
PARMS=xxxxxxxx Invocation Parameter Group name is not supported.

For MVS batch applications, the NLS, DMODE, and PARMS invocation parameters are handled as shown in Table 8 for MVS/TSO. The U invocation parameter for MVS batch applications is not supported. The EZEUSR and EZEUSRID statements are always set to the job name from the job card.

Table 9 shows how VSE CICS invocation parameters are supported when using generated COBOL applications.

Table 9. Invocation Parameter Migration for VSE CICS
Parameter Corresponding Function in VisualAge Generator
P=yyyy The application developer can specify an alternate transient data or spool file during generation by using a resource association file. The application can dynamically change the target transient data queue name or POWER spool file name by using the special word EZEDESTP.
NLS=n The NLS code for VisualGen Host Services is specified at generation time with the /TARGNLS generation option.
SEG The application switches between segmented and nonsegmented mode by setting EZESEGM.
SMODE=S|D|A You choose whether DB2/VSE or ANSI SQL statements are generated using the /ANSISQL generation option. DB2/VSE SQL statements or ANSI SQL statements are imbedded directly into the generated COBOL application. SMODE=D (dynamic execution) is not supported.
SID All of the SQL calls are handled by COBOL statements. For VSE CICS, DB2/VSE automatically connects the application user to the database at the first SQL call using the implicit user ID for CICS. If the application user is signed on as a VSE/ESA interactive user interface user, the implicit CICS user ID is connected with that VSE/ESA user ID. Otherwise, it is the CICS default set by the CIRB transaction. If you want to use an ID other than the implicit ID, your application must issue an EZECONCT call with the desired user ID and password prior to the first SQL process option.

For VSE batch, VisualGen Host Services has to connect the application user to the database before the first SQL call. The SID=userid/password parameter specified in SYSIPT of the job is used to perform this database connection.

RT=zzzz The RT option is specified at generation time through the /RT generation option. The application user no longer has to press attention interrupt to go on to the next transaction; the transaction is started automatically.
TSMS The /WORKDB generation option specifies whether auxiliary or main temporary storage is used for saving working storage across segments.
FFFF The /MARKLISTEND generation option specifies whether the end of list indicator is used.

For VSE batch applications, the NLS, SMODE, and PARMS invocation parameters are handled as shown in Table 9 for VSE CICS. The U invocation parameter for VSE batch applications is not supported. The EZEUSR and EZEUSRID statements are always set to the job name from the job card.

Table 10 shows how VM invocation parameters are supported when using generated COBOL applications.

Table 10. Invocation Parameter Migration for VM
Parameter Corresponding Function in VisualAge Generator
P=filename The application developer can specify a serial or print file during generation by using a resource association file. The application can dynamically change the target serial file or print file by using the special word EZEDESTP.
NLS=X The NLS code for VisualGen Host Services is specified at generation time with the /TARGNLS generation option.
LL=xxxxxxxx There is no equivalent of the CSP LL= invocation parameter. A CALL statement to the non-VisualAge Generator program is generated in the COBOL program. This causes the CMS search order to be searched for a CMS module that matches the non-VisualAge Generator program name. If one is not found, the LOADLIBs in the GLOBAL LOADLIB list is searched for a match. If still no match is found, an attempt is made to find a TEXT file with same file name.
SMODE=M|S|D|A DM|DS|MD|SD For SMODE=A, you can choose whether SQL/DS or ANSI SQL statements are generated using the /ANSISQL generation option. SQL/DS statements or ANSI SQL statements are imbedded directly into the generated COBOL application. SMODE=D (dynamic execution) is not supported. SMODE=S (single-user mode) or SMODE=M (multi-user mode) are defined by the user-defined symbolic parameter SQLSTMDE and are used during application generation. The default is SQLSTMDE=MULTIUSER. If SQLSTMDE=SINGLEUSER, the user-defined symbolic parameter SQLSTOPT can be used to specify the file name of a file containing SQL/DS startup options. Other SQL/DS user-defined symbolic parameters are SQLDBNAM, SQLPKGNM, SQLPROPT, and SQLUSRPW. Refer to the Generating VisualAge Generator Applications and the Running VisualGen Applications on VM documents for more information.
SID= All of the SQL calls are handled by COBOL statements. In VM, there are several ways to handle the connection to the SQL database.

For VM, if no user ID and password are specified, SQL/DS connects the application user to the database at the first SQL call using the VM user ID and password.

If you want to use an ID other than the implicit ID, your application can issue an EZECONCT call with the desired user ID and password prior to the first SQL process option.

During generation, you can use the /SQLUSRPW symbolic parameter to specify the user ID and password to be used for the SQL connection.

In addition, the user can specify the SID= parameter on the application runtime REXX exec to specify the user ID and password to be used for the database connection during the execution of the application. Refer to the Generating VisualAge Generator Applications and the Running VisualGen Applications on VM documents for more information.

SDB= For VM, if no database name is specified, SQL/DS connects the application user to the database at the first SQL call using the database specified on the last SQLINIT issued for the virtual machine.

If you want to use a database other than the implicit database, your application can issue an EZECONCT call with the desired user ID, password, and database name prior to the first SQL process option.

During generation, you can use the /SQLDBNAM symbolic parameter to specify the database name to be used for the SQL connection.

In addition, the user can specify the SDB= parameter on the application runtime REXX exec to specify the database name to be used for the database connection during the execution of the application. Refer to the Generating VisualAge Generator Applications and the Running VisualGen Applications on VM documents for more information.

ALF=C|V VisualGen Host Services does not have an equivalent of the ALF parameter. All applications reside in the CMS LOADLIB. The LOADLIB name is specified in the runtime exec.
NOTXA Use the /DATA=24 generation option to force all working storage to be acquired below the line.
SS=YES|NO VisualGen Host Services product code is always loaded from the product LOADLIB. Loading the product code from a shared segment is not supported.

In the VM CMS and VM batch environments, a generated main transaction or main batch program is invoked by a runtime REXX exec. A sample runtime exec specifically for the application is created by the COBOL generator if the /RUNFILE option is specified. The sample runtime REXX exec might need to be modified before it is used. Refer to the Running VisualGen Applications on VM document for more information on tailoring the sample runtime REXX exec.


National Language Applications

When installing different national language versions of an application on the same CICS system using CSP/AE, you generate each version into a different ALF and have the user select the appropriate ALF when starting the transaction. In VisualAge Generator, you have to change the application name and assign a separate transaction code for each national language version of the application.

Map groups and language-dependent tables also need to have different names for each language. This is because programs in MVS CICS, VSE CICS, and CICS OS/2 systems must have unique names.


Non-VisualAge Generator Interface to DCBRINIT on MVS CICS and VSE CICS CONVERSEs

If you are migrating to VisualAge Generator from CSP/AE, you might have used a non-Cross System Product program to interface to either DCBINIT (the CSP/AE interpreter) or to DCBRINIT (the CSP/AE routine to restart after a segmented CONVERSE). In CSP/370AD 4.1 and CSP/370RS 2.1, if you used both CSP/AE applications and generated COBOL applications or you used only generated COBOL applications and you wanted to continue to run a non-VisualAge Generator program during a segment break, the module ELATSRST was used in place of DCBRINIT. VisualAge Generator also provides the ELATSRST module.

Some CSP/AE customers developed systems whereby the initial program receiving control from CICS was always a non-CSP/AE program. This occurred even when the transaction was a segment started following the CONVERSE process option from a pseudoconversational application. The non-CSP/AE program transfers control using the XCTL statement to DCBINIT (the CSP/AE interpreter) or DCBRINIT (CSP/AE interpreter segment restart) to continue processing using CSP/AE.

The techniques described in this session enable you to implement these functions using a VisualGen Host Services module, ELATSRST, instead of DCBINIT or DCBRINIT. ELATSRST is provided as a migration aid. It should not be used for new applications. Consider the following before you use ELATSRST:

See for an example of a CSP/AE application:

Figure 9. Sample CSP/AE Application

trancode X ------- trancode Y
 
     PROGA     started by CICS
         - does some common, front-end processing
         - determines which application is associated with
           the transaction code
         - creates a COMMAREA with the ALF name, application name and
           possibly working storage
         - issues a CICS XCTL command to DCBINIT
 
     DCBINIT
         - starts the requested application
         - the application
         - sets EZESEGTR to a new transaction code (trancode Y)
         - does a segmented CONVERSE
 
application user enters data
trancode Y -------
 
     PROGB    started by CICS
         - does some common, front-end processing
         - issues a CICS XCTL command to DCBRINIT
 
     DCBRINIT
         - determines which application to resume
         - resumes processing for the application after the
           segmented CONVERSE

See for a sample technique with VisualGen Host Services:

Figure 10. VisualGen Host Services Example

trancode X ------- trancode Y
 
     PROGA     started by CICS
         - does some common, front-end processing
         - determines which application is associated with
           the transaction code
         - determines whether the application is generated for CSP/AE or as
           a COBOL application
         - if the application is generated for CSP/AE
           - creates a COMMAREA with the ALF name, application name and
             possibly working storage
           - issues a CICS XCTL command to DCBINIT
         - if the application is generated as a COBOL application
           - creates a COMMAREA containing the working storage record,
             if any, for the application
           - issues a CICS XCTL command to the application
           - the COBOL application sets EZESEGTR to a new
             transaction code (trancode Y) and then does
             a segmented CONVERSE
 
     DCBINIT
         - starts the requested application
         - the application
           - sets EZESEGTR to a new transaction code (trancode Y)
           - does a segmented CONVERSE
 
application user enters data
trancode Y -------
 
     PROGB    started by CICS
         - does some common, front-end processing
         - issues a CICS XCTL command to ELATSRST
 
     ELATSRST
         - determines whether the application being restarted
           was generated for CSP/AE or as a COBOL application
         - if it was generated for CSP/AE
           - issues a CICS XCTL command to DCBRINIT
         - if it was generated as a COBOL application
           - issues a CICS XCTL command to the application
         - a CICS abend occurs if either the XCTL is unsuccessful or
           other CICS detectable conditions occur (e.g. AE10)
         - a VisualGen Host Services abend, ELAF, occurs if CSP/370 Runtime Services
           detectable errors are found (e.g. not resuming after a
           CONVERSE).
         - application resumes processing
 
     DCBRINIT
         - determines which application to resume
         - resumes processing for the application after the
           segmented CONVERSE.

To implement the transfer using ELATSRST the following changes are needed:


Transferring Application Control

Existing non-Cross System Product programs that use CSP/AE linkage conventions to call CSP/AE applications must be rewritten to use standard COBOL linkage conventions if the applications are generated again as a VisualAge Generator COBOL programs.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]