
README.TXT for CICS OS/2 V2.0 - CSD 04 - 27 January 1995.


  This file documents the latest updates to the CICS for OS/2 system.
  *******************************************************************


                     CICS for OS/2 Documentation Changes
                     -----------------------------------

  As part of this CSD all of the CICS for OS/2 documentation is shipped
  as OS/2 VIEWable files. There are a number of additional files which
  are located in the \CICS200\BOOKS directory. They are as follows:

  o        FAAAPPRG.INF      The application programming guide.
  o        FAACSP.INF        The client/server programming guide. (NEW)
  o        FAAICOMM.INF      The inter-communications guide.
  o        FAAINST.INF       The installation guide.
  o        FAARSUM.INF       The reference summary.               (NEW)


                     Changes for APARs PN53736 / PN62677
                     -----------------------------------

  The CICS for OS/2 API for the SET and INQUIRE verbs has been enhanced
  with this CSD. For a full description of the SET and INQUIRE verbs
  please refer to the Application Programming Guide in file:

  o        \CICS200\BOOKS\FAAAPPRG.INF


                     CICS for OS/2 Command File Changes
                     ----------------------------------

  With the installation of this CSD there are new versions of all of the
  CICSxxxx.CMD files. These new files have been created in the directory
  \CICS200\SAMPLES\CMD. In addition backups of the existing CICSxxxx.CMD
  files have been made into \CICS200\SAMPLES\CMD\CICSxxxx.BAK files.

  The existing command files have NOT been changed.

  If you wish to take advantage of these new command files we suggest
  that you migrate any changes that you may have made to your old
   \CICS200\UTIL\CICSxxxx.CMD files into the new files and then copy
  the new files from the \CICS200\SAMPLES\CMD into \CICS200\UTIL.


                     PL/I Support Information
                     ------------------------

  Sections:

    1. CICS for OS/2 Environment

    2. PL/I Considerations
       o Restrictions
       o PL/I STAE option
       o OPTIONS(MAIN) specification

    3. Coding BMS definition macros

    4. Writing PL/I application programs

    5. Preparing PL/I application programs

    6. Preparing ECI, EPI and ETI application programs

    7. Debugging PL/I application programs

  --------------------------------------------------------------

    1. CICS for OS/2 Environment
       o The CICSxxx\BIN (e.g.CICS200\BIN) directory that contains the
         CICS for OS/2 system modules, must reside in the LIBPATH.

       o The PL/I run-time modules must reside in the LIBPATH.
         The message:
           FAA5638I PL/I run-time interface loaded
         will appear on the CICS for OS/2 message log upon successful
         loading of the PL/I run-time.

       o Some PL/I applications may require a very large stack.
         Debugging using PLITEST may demand such a large stack.
         If the default PL/I stack size of 1024k is insufficient,
         then the environment variable CICSSTACK may be set to
         the required value in kilobytes, eg.
           'SET CICSSTACK=2048'
         would set the PL/I program stack size to 2MB.
         This can be placed in the CICSRUN.CMD supplied command file.

       o The CICSENV.CMD supplied command file that sets up your
         CICS for OS/2 environment, has an additional variable
         UserPLICeeOptions. This is for setting your desired
         PL/I CEE.OPTIONS environment. The default setting in the
         supplied command file is CEE.OPTIONS=NOTEST.
         When using PLITEST be sure to set this option to TEST.

    2. PL/I Considerations

       o PL/I STAE option

         By default the PL/I STAE option is in effect for all
         PL/I programs. In the CICS for OS/2 environment, this
         implies an EXEC CICS HANDLE ABEND at PL/I program
         initialization of a CICS PL/I abend handler. The
         action of this abend handler is to raise ERROR 9050
         (abend has occurred), which can be handled by a user's
         error on unit. If there is no error on unit, or the
         on unit takes normal exit, then the default action is
         to abend the PL/I program with the original CICS abend
         code.

         The use of the PL/I NOSTAE option is not supported.

         If the user PL/I program issues its own EXEC CICS HANDLE
         ABEND, then this overrides the CICS PL/I abend handler.

       o OPTIONS(MAIN) specification

         If OPTIONS(MAIN) is specified in an application program,
         that program can be the first program of a transaction,
         or control can be passed to it by means of a LINK or XCTL
         command.

         If OPTIONS(MAIN) is not specified, it cannot be the first
         program in a transaction, nor have control passed to it
         by a LINK or XCTL command, but it can be link-edited to
         a main program DLL.

         The definition of the EIB (DFHEIBLK) is generated in each
         program, based upon the pointer variable DFHEIPTR.
         In programs declared with OPTIONS(MAIN), the DFHEIPTR
         variable is set up to address the EIB on entry.
         However, in programs other than those that have
         OPTIONS(MAIN), addressability to the EIB is the user's
         responsibility.

         Addressability is achieved by using the command:

         EXEC CICS ADDRESS EIB(DFHEIPTR)

         or by passing the EIB address or particular fields therein
         as arguments to the CALL statement that invokes the external
         procedure.

  --------------------------------------------------------------

    3. Coding BMS definition macros

      The BMS map set definition macro DFHMSD, now supports
      the following source language values:

                        COBOL
        DFHMSD ... LANG=C
                        PLI

      The BMS field definition macro DFHMDF, now supports
      PICIN and PICOUT for both COBOL and PL/I.

      Note: The CICSMAP BMS translator command file places the
      mapset.INC copybook in the first directory specified in
      the INCLUDE path environment variable.

  --------------------------------------------------------------

    4. Writing PL/I application programs

       Compilers supported
       -------------------
       You can use the IBM PL/I for OS/2 Professional Edition to
       process your PL/I application programs.

       CICS for OS/2 API supported in PL/I
       -----------------------------------
       The full CICS for OS/2 API as detailed in the Programming
       Reference, is supported for PL/I application programs,
       apart from the following commands:

       EXEC CICS HANDLE ABEND LABEL(label)

       Argument Values
       ---------------
       o "data-value" (data name or constant)
         - Halfword binary  - FIXED BINARY(15)
         - Fullword binary  - FIXED BINARY(31)
         - Character string - CHARACTER(n)

       o "data-area" (data name)
         - Halfword binary  - FIXED BINARY(15)
         - Fullword binary  - FIXED BINARY(31)
         - Character string - CHARACTER(n)

       o "cvda"
         - CVDA area  - FIXED BINARY(31)
         - CVDA value - DFHVALUE(cvda name)
         - Implicit CVDA on CICS API command - eg.
           EXEC CICS SET PROGRAM(program) ENABLED

       o "pointer-value" or "pointer-ref"
         - PL/I pointer - POINTER

       o "name"
         - A character string in single or double quotes
         - Character string - CHARACTER(n)

       o "label"
         - PL/I label - LABEL

       o "hhmmss"
         - Decimal constant or data name - FIXED DECIMAL(7)
           The value must be of the form 0HHMMSS.

       Default length options in CICS commands
       ---------------------------------------
       In PL/I programs the translator defaults certain length
       options; that is, there is no need to code the LENGTH
       option for a data area if the length of the field is
       being passed to CICS. The default length used is
       STORAGE(data-area) or CURRENTSTORAGE(data-area).

       Sample PL/I programs
       --------------------
       A set of sample application programs is provided to show
       how CICS commands can be used in a program written in PL/I.
       These programs have file names FAADP*.PLI.
       The PL/I sample programs are:

         FAADPALL.PLI - FILEA Add/Inquire/Update
         FAADPBRW.PLI - FILEA Browse
         FAADPCOM.PLI - FILEA Order entry queue print
         FAADPMNU.PLI - FILEA Operator instruction menu
         FAADPREN.PLI - FILEA Order entry
         FAADPREP.PLI - FILEA Low balance report

       The PL/I include files are:

         FAADPL86.INC
         FAADPFIL.INC
         FAADPLOG.INC

       The corresponding BMS maps are:

         FAADPMA.BMS
         FAADPMB.BMS
         FAADPMC.BMS
         FAADPMD.BMS
         FAADPMK.BMS
         FAADPML.BMS

       To run the sample transactions, proceed as follows:

         1. Ensure your PL/I compiler environment is set up.

         2. Run the BMS map translator against each of the map files.
           For example: CICSMAP FAADPMA. This generates the maps
           themselves, and produces the PL/I copybooks FAADPM*.INC
           in the first directory specified in the INCLUDE path
           environment variable.

         3. Translate, compile and link each of the application
           programs. For example: CICSPCLK FAADPALL.

           This will create the FAADP*.DLL in the first directory in
           the CICSWRK environment path.

         4. Bring up CICS for OS/2 and define the following entries in
           the PCT and FCT using the CEDA transaction or by importing
           the FAAIVP group definitions using the CAIM transaction:

           PADD  - FAADPALL
           PBRW  - FAADPBRW
           PCOM  - FAADPCOM
           PINQ  - FAADPALL
           PMNU  - FAADPMNU
           PORQ  - FAADPCOM
           PREN  - FAADPREN
           PREP  - FAADPREP
           PUPD  - FAADPALL

           FILEA - FILEA file definition

         5. Copy the file CICSxxx\SAMPLES\DATA\FILEA.BTR to
           the CICSxxx\BIN\DATA directory.

         6. Shut down CICS for OS/2 using the CQIT transaction.

         7. Bring up CICS for OS/2 (to make the PCT and FCT entries
            active).

         The transaction names are:

           PMNU - For the menu
           PBRW - To browse records (from the menu)
           PADD - To add records (from the menu)
           PINQ - To make inquiries (from the menu)
           PUPD - To update records (from the menu)
           PREN - To run the order entry program
           PORQ - To run the order entry queue print program
           PREP - To run the low balance report program

       Using PL/I programs under CICS for OS/2
       ---------------------------------------
       CICS for OS/2 V2.0.1 is 16 bit based; therefore, no memory
       object being passed to or from CICS for OS/2 may be larger
       than 64KB or may span a 64KB boundary. Memory that can be
       referred to using a (0:32) or a (16:16) address is known as
       TILED memory. You can ensure that objects meet this criterion
       by compiling your 32 bit PL/I programs with the TILED option,
       this is the default option used by the supplied command file
       CICSPCMP.

  --------------------------------------------------------------

    5. Preparing PL/I application programs

       Commands for preparing PL/I applications
       ----------------------------------------
       CICSPCLK - A command file that translates, compiles and
                  links a PL/I program.

       CICSPCMP - A command file that translates and compiles
                  PL/I programs.

       CICSPLNK - A command file that links a PL/I program.

       These command files are provided in the CICSHLD\UTIL
       directory. You may want to change them to suit your
       own environment.

       Specifying CICS API Translator Options
       --------------------------------------
       The CICS API translation of a PL/I program actually
       occurs during the PL/I compilation as a CICS
       preprocessor pass. Translator options are passed
       as a character string to the PL/I compiler on the
       CICS preprocessor option, for example:

         CICSPCMP program ( pp(cics('noedf') macro)

       The minimum preprocessor options required for PL/I CICS
       translation are:

         pp(cics macro)

       The macro preprocessor pass is required to resolve
       DFHRESP() and DFHVALUE() macros.

       CICS preprocessor options:
         (NO)SOURCE      - Source program only output in compiler listing
         (NO)PRINT       - Complete source output in compiler listing
         (NO)DECK        - Produce program.DEK generated output listing
         (NO)EDF         - EDF enable program
         (NO)DEBUG       - DEBUG enable program

       Default options:
           NOSOURCE NOPRINT NODECK EDF DEBUG

       Files used in preparing PL/I programs and map sets
       --------------------------------------------------

       File           Content           Produced by
       ----           -------           -----------
       setname.BMS    Map set source    User
       setname.TRL    Map translator    Map translator
                      message file
       FAAMSFSC.BTR   User map set      Map translator
                      master file
       setname.INC    Map set copybook  Map translator
       progname.PLI   Program source    User
       progname.LST   Program compiled  PL/I compiler
                      listing
       FAAPSTRT.LIB   CICS run-time     Supplied with
       FAAPLID.LIB    libraries         CICS for OS/2
       FAAOTSPL.LIB
       IBMLINK.LIB    PL/I run-time     Supplied with
       CEELINK.LIB    libraries         PL/I
       progname.OBJ   Compiled program  PL/I compiler
       progname.DEF   Module definition User or default
                      file              created by CICS for OS/2
       progname.DLL   Linked program    Linkage editor
       progname.MAP   Program map       Linkage editor


       CICSPCMP: Translate and compile a PL/I program
       ----------------------------------------------

       Syntax:

       CICSPCMP Pliprogs ( UserCompilerOptions

       Pliprogs            - A list of PL/I source programs to be
                             translated and compiled.

       UserCompilerOptions - Additional user PL/I compiler options.

       The following PL/I compiler directives are used as default by
       the CICSPCMP command file:

         system(cics) pp(cics("deck print") macro) tiled source not("^")

       Example:

       CICSPCMP faadpall faadpbrw ( default(ebcdic nonnative)

       CICSPLNK: Link a PL/I program
       -----------------------------

       Syntax:

       CICSPLNK UserLinkOptions LinkObjects

       UserLinkOptions - Additional user linkage editor options.

       LinkObjects     - A list of the program object decks to be
                         linked into the program.DLL. The first
                         program object in this list must be the
                         name of the program.DLL and program.DEF
                         created.

       The following link options are used as default by
       the CICSPLNK command file:

         /MAP /NOD

       When using PLITEST the program should be linked with the
       /De linker option.

       Note: The program.DLL is placed in the first directory in
       the CICSWRK environment path.

       The default program.DEF file created by the CICSPLNK
       command file is:

         ;Module definition file for CICS for OS/2 programs using PL/I
         LIBRARY INITINSTANCE TERMINSTANCE
         PROTMODE
         CODE LOADONCALL SHARED
         DATA MULTIPLE NONSHARED
         EXPORTS program        @1
                 FAA_PROGRAM_ID @2

       Note: The program export name must be the same as the name
       of the options(main) procedure.

       Note: If the user supplies their own program.DEF file
       then it must export the two entries specified in the above
       module definition.

       Example:

       CICSPLNK /noe faadpall

       CICSPCLK: Translate, compile and link a PL/I program
       ----------------------------------------------------

       Syntax:

       CICSPCLK Pliprogs ( UserCompilerOptions

       Pliprogs            - A list of PL/I source programs to be
                             translated and compiled.
                             The first program in this list must be the
                             name of the program.DLL and program.DEF
                             created.

       UserCompilerOptions - Additional user PL/I compiler options.

       Note: The CICSPCLK command file invokes the command files
       CICSPCMP and CICSPLNK.

       Example:

       CICSPCLK faadpall ( default(ebcdic nonnative)

       ASCII/EBCDIC and NATIVE/NONNATIVE support
       -----------------------------------------

       CICS for OS/2 PL/I applications can be compiled with the
       ASCII/EBCDIC character set and NATIVE/NONNATIVE binary
       format default options.

       These options are specified as defaults when compiling
       your PL/I application programs, eg:

       CICSPCMP faadpall ( default(ebcdic nonnative)

  --------------------------------------------------------------

    6. Preparing ECI, EPI and ETI application programs

       Making External Call Interface (ECI) calls
       ------------------------------------------
       Example:
         %include cics_eci; /* CICS_ECI.INC ECI definitions */

         Declare eci_parms_s         TYPE ECI_PARMS,
                 Response            FIXED BINARY(15);
                       .
                       .
         Response = FaaExternalCall (eci_parm_s);

       Sample Program:
         CICSHLD\SAMPLES\PLI\SOURCE\ECIWAIT.PLI - Source
         CICSHLD\SAMPLES\PLI\SOURCE\ECIWAIT.LP  - LINK386 response file
         CICSHLD\SAMPLES\PLI\SOURCE\ECIWAIT.PEF - Module .DEF file

       Making External Presentation Interface (EPI) calls
       --------------------------------------------------
       Example:
         %include cics_epi; /* CICS_EPI.INC EPI definitions */

         Declare System           TYPE CICS_EpiSystem_t,
                 Details          TYPE CICS_EpiDetails_t
                 Index            FIXED BINARY(16) UNSIGNED,
                 Response         FIXED BINARY(15);
                       .
                       .
         Declare Count            FIXED BINARY(16) UNSIGNED,
                 Server_List(3)   TYPE CICS_EpiSystem_t,

         Count    = 3;
         Response = CICS_EpiListSystems(null(),
                                        Count,
                                        Server_List(1));

       Sample Program:
         CICSHLD\SAMPLES\PLI\SOURCE\EPISAMP.PLI - Source

       Making External Transaction Initiation (ETI) calls
       --------------------------------------------------
       Example:
         %include cics_eti; /* CICS_ETI.INC ETI definitions */

         Declare eti_parms_s      TYPE ETI_PARMS,
                 Response         FIXED BINARY(15);
                       .
                       .
         Response = FaaExternalTrans (eti_parms_s);

  --------------------------------------------------------------

    7. Debugging PL/I application programs

       Execution Diagnostic Facility (EDF)
       -----------------------------------

       EDF allows step by step execution of EXEC CICS
       statements in your application program. To enable this
       facility for your PL/I program, the CICS PL/I preprocessor
       option EDF must be enabled, this is the default if it is
       not specified. To disable EDF, the NOEDF option should be
       specified, for example:

         CICSPCMP faadpall ( pp(cics('noedf') macro)

       PL/I PLITEST Source Level Debugger
       ----------------------------------

       The PL/I compiler provides a source level debugger
       called PLITEST. To PLITEST enable your PL/I program, compile
       it using the PL/I TEST option, for example:

         CICSPCMP faadpall ( test

       To enable your CICS PL/I application to be debugged using
       PLITEST, the CEE.OPTIONS run-time option TEST must be in
       affect. The default setting in the CICSENV.CMD supplied
       command file for UserPLICeeOptions is NOTEST. This option
       should be changed to TEST to enable PLITEST debugging.
       This run-time option can be dynamically changed for a given
       terminal by using the CPOP transaction supplied with CICS
       OS/2. This change occurs only for the terminal that the
       transaction is run from, allowing you to have each
       terminal with unique settings for this option.

       The syntax for the run-time option TEST is as follows:

                   *-ERROR-*   *-*-*   *-PROMPT---*   *-*-*
                   |       |   |   |   |          |   |   |
       >>--*-TEST(-*-------*-,-*---*-,-*----------*-,-*---*-)-*-><
           |       |       |           |          |           |
           |       *-ALL---*           *-NOPROMPT-*           |
           |       |       |           |          |           |
           |       *-NONE--*           *-;--------*           |
           |                           |          |           |
           |                           *-*--------*           |
           *-NOTEST-------------------------------------------*

       SYSPRINT, MSGFILE, DISPLAY and PLIDUMP Output
       ---------------------------------------------

       With the CEE.OPTIONS run-time option NOTEST in affect, the
       output from SYSPRINT, MSGFILE and DISPLAY is written to
       the CICS Transient Data Queue (TDQ) CPLI.

       The output from PLIDUMP is always written to the CICS
       Transient Data Queue (TDQ) CPLD, whether the TEST or NOTEST
       option is in affect.

       Testing PL/I Applications
       -------------------------

       For performance reasons CICS for OS/2 keeps the last program run
       in memory until a different program is needed. You may not be
       able to relink a program that was just executed unless you cause
       CICS for OS/2 to "unload" it. This can be accomplished by running
       any other transaction (e.g. CPOP, CEDA) from the same terminal.

  --------------------------------------------------------------

  **************************************************************

  **************************************************************
  **************************************************************
  ***                                                        ***
  ***                   End of Document                      ***
  ***                                                        ***
  **************************************************************
  **************************************************************
