The translation process

For compilers without integrated translators, CICS® provides a translator program for each of the languages in which you may write, to handle EXEC CICS, EXEC CPSM and EXEC DLI statements. For compilers with integrated translators, the compilers call the CICS translator directly to handle the translation of these commands.

A language translator reads your source program and creates a new one; most normal language statements remain unchanged, but CICS commands are translated into CALL statements of the form required by the language in which you are coding. The calls invoke CICS-provided EXEC interface modules, which later get link-edited into your load module, and these in turn invoke the requested services at execution time.

There are three steps: translation, compilation (assembly), and link-edit. Figure 1 shows these 3 steps.

Figure 1. Preparing an application program
This picture shows how the source program is translated to a SYSPUNCH source file, which is then compiled to create an OBJECT MODULE and a compiler listing. The object module is link-edited to form a LOAD MODULE, which is then stored in the LOAD LIBRARY.

If your system administrator has defined rules that identify restricted CICS API and SPI commands in the restricted commands parmlib member DFHAPIR, during translation the CICS translator also checks your source program against the restricted commands and keywords. In case of violation, the CICS translator will issue warning or error messages, and the translation might fail. For more information, see Controlling the use of specific CICS API and SPI commands.

The translators for all languages use one input and two output files:
SYSIN
(Translator input) is the file that contains your source program.

If the SYSIN file is defined as a fixed blocked data set, the maximum record length that the data set can possess is 80 bytes. Passing a fixed blocked data set with a record length of greater than 80 bytes to the translator results in termination of translator execution. If the SYSIN file is defined as a variable blocked data set, the maximum record length that the data set can possess is 100 bytes. Passing a variable blocked data set with a record length greater than 100 bytes to the translator causes the translator to stop with an error.

SYSPUNCH
(Translated source) is the translated version of your source code, which becomes the input to the compilation (assemble) step. In this file, your source has been changed as follows:
  • The EXEC interface block (EIB) structure has been inserted.
  • EXEC CICS , EXEC CPSM and EXEC DLI commands have been turned into function call statements.
  • CICS DFHRESP, EYUVALUE, and DFHVALUE built-in functions have been processed.
  • A data interchange block (DIB) structure and initialization call have been inserted if the program contains EXEC DLI statements.

The CICS commands that get translated still appear in the source, but as comments only. Generally the non-CICS statements are unchanged. The output from the translator always goes to an 80 byte fixed-record length data set.

SYSPRINT
(Translator listing) shows the number of messages produced by the translator, and the highest severity code associated with any message. The options used in translating your program also appear, unless these have been suppressed with the NOOPTIONS option.

For COBOL, C, C++, and PL/I programs, SYSPRINT also contains the messages themselves. In addition, if you specify the SOURCE option of the translator, you also get an annotated listing of the source in SYSPRINT. This listing contains almost the same information as the subsequent compilation listing, and therefore many installations elect to omit it (the NOSOURCE option). One item you may need from this listing which is not present in the compilation listing, however, is the line numbers, if the translator is assigning them. Line numbers are one way to indicate points in the code when you debug with the execution diagnostic facility (EDF). If you specify the VBREF option, you also get a list of the commands in your program, cross-referenced by line number, and you can use this as an alternative to the source listing for EDF purposes.

For assembler language programs, SYSPRINT contains only the translator options, the message count and maximum severity code. The messages themselves are inserted into the SYSPUNCH file as comments after the related statement. This causes the assembler to copy them through to the assembler listing, where you can check them. You may also see MNOTEs that are generated by the assembler as the result of problems encountered by the translator.

Note: If you use EXEC SQL, you need additional steps to translate the SQL statements and bind.

CICS provides a procedure to execute these steps in sequence for each of the languages it supports. Using the CICS-supplied procedures to install application programs describes how to use these procedures, and exactly what they do.

You can control the translation process by specifying a number of options. For example, if your program uses EXEC DLI calls, you need to tell the translator.

The translator may produce error messages, and it is as important to check these messages as it is to check the messages produced by the compiler and link-editor. See The CICS-supplied translators for the location of these messages.

EXEC commands are translated into CALL statements that invoke CICS interface modules. These modules get incorporated into your object module in the link-edit step, and you see them in your link-edit output listing. You can read more about these modules in The CICS-supplied interface modules.