Sun Mainframe Transaction Processing Software Developer's Guide

Sun MTP provides support for Liant Open PL/I and the shared library functionality required to execute PL/I applications. This chapter describes how to use PL/I shared libraries.

The Liant documentation describes the preprocessor kixplt as residing in $LPI_PRODUCT_DIR/bin. However, this is an older version of kixplt. The most current version is located in $UNIKIX/bin. It is strongly recommended that you use the newer version of kixplt. The makefile that is built using the kixinstall configuration utility automatically looks for kixplt in $UNIKIX/bin. However, all user-written scripts and makefiles should now also look for kixplt in $UNIKIX/bin.

This chapter contains the following topics:

• Setting Up Shared Libraries
• Using LOAD PROGRAM ENTRY With Shared Libraries
• Using CEMT With Shared Libraries
• Building Shared Libraries

See Debugging PL/I Programs for information about CodeWatch, the PL/I debugger.

Also, refer to the Linker and Libraries Guide, which is available on docs.sun.com. This document provides detailed information about building and maintaining shared objects.

---

Setting Up Shared Libraries

All PL/I application programs must be executed from one or more shared libraries that were previously built using the UNIX shared library facility. See Building Shared Libraries.

Each PL/I program and the corresponding shared library in which it resides must be identified to the region in the Program Processing Table (PPT). Refer to the Sun Mainframe Transaction Processing Software Reference Guide for a description of the PPT.

Naming Shared Libraries

Observe these requirements when naming shared libraries:

• All shared library entries in the PPT must be relative to the $KIXSYS directory, unless you have defined the KIXLIB environment variable. If $KIXLIB is set, it contains a list of path names that specify which directories to search for shared libraries. Refer to the Sun Mainframe Transaction Processing Software Configuration Guide for information about setting environment variables.
• The PPT entry for the shared library name is a maximum of 16 characters including any subdirectory names but not including the .so extension. This limits the length and number of subdirectories below the $KIXSYS or $KIXLIB level.
• Shared libraries names must be lowercase.
• The actual shared library is built with a .so extension, but the .so extension is not used in the PPT. When allocating a library, Sun MTP appends the extension to the library name it retrieves from the PPT.
• Two libraries can have the same name as long as some part of the path is unique.

For example, legal library names are:

lev1/lev2/myshlb: Maximum length for a PPT entry (note that .so is not part of the name in Sun MTP). This entry has two subdirectory levels before the shared library.

mysharedlib: Shared library with no subdirectory levels.

Opening Shared Libraries

Each shared library listed in the PPT corresponds to its specified transaction. An individual shared library is not opened until its corresponding transaction is invoked. This method of opening shared libraries keeps the startup overhead low, ensuring that only invoked shared libraries are opened. However, once a shared library is opened, it is not unloaded (or closed) when its transaction terminates; it remains in a state of readiness for the next invocation of the same transaction.

Because the loading algorithm for application shared libraries is based on the invocation of the corresponding program, any symbol reference dependencies must be declared on the link line at the time the particular shared library is built see Link Line Examples for Building a Shared Library); otherwise those symbols will not be available for the Dynamic Loader to resolve.

Another way to make dependency symbols available to the dynamic loader is to set the pre-load (P/L) field in the PPT entry to Y for the shared library. When you set this field to Y, the transaction server will open all the pre-load shared libraries when it starts up. If every shared library in the PPT has its pre-load field set to Y, then all shared libraries are loaded when the region starts.

Link Line Examples for Building a Shared Library

This link line example shows the building of a shared library named prog1.so with dependencies in another shared library called libmoreso.so.

$ ld -G -Bdynamic  -o prog1.so prog1.o -R $KIXLIB/mysos1 \-L $KIXLIB/mysos1 -lmoreso

PPT Pre-load Field

Each PPT entry has a single-character field labeled P/L. You must set this field to Y to indicate if the shared library is to be pre-loaded. Otherwise, set this field to N or leave it blank.

FIGURE 6-1 illustrates the PPT main screen, which shows one shared object whose P/L field is set to Y. In this example, the entries show C shared objects.

  FIGURE 6-1 PPT--Shared Library Entries

---

Using LOAD PROGRAM ENTRY With Shared Libraries

On a mainframe, the EXEC CICS LOAD PROGRAM ENTRY statement returns the entry address of the requested program. The user application can save the address for later use or invoke the program immediately.

In Sun MTP, however, the command behaves differently. Pointers into shared libraries that are acquired by one transaction processor cannot be reliably used at a later time by a different transaction processor because of the UNIX shared library implementation. (Pseudo-conversational transactions can execute in one or more transaction processors during the course of the transaction.) In this implementation, the pointer returned by the EXEC CICS LOAD PROGRAM ENTRY statement is a pointer into shared memory that must be converted to a "real" shared entry pointer when a particular process ID, that is, transaction processor, wants to invoke the desired program. The address returned can be saved for later use. However, just before it is used as an entry address, it must be translated by a special function named KXSYM2FUNC, as illustrated in these examples.

The examples shown in CODE EXAMPLE 6-1 and CODE EXAMPLE 6-2 illustrate the ENTRY option of the LOAD command. Omitted code is indicated by an ellipsis (...). These fragments can be in different PL/I procedures that execute in different Sun MTP transaction server processes, but the LOAD must occur before KXSYM2FUNC is called.

The code in the following example acquires storage for a global table that includes a pointer to a procedure, perhaps a routine that handles the user interface, data editing or database access. The loaded procedure, MYPROC, must have an entry in the PPT.

...

DCL TABLE_PTRPOINTER;

DCL 1 TABLE BASED(TABLE_PTR),

	2 ...

	2 PROC_PTRPOINTER;

	...

EXEC CICS GETMAIN

		LENGTH(STG(TABLE))

		SET(TABLE_PTR)

		SHARED;  

...

EXEC CICS LOAD

		PROGRAM('MYPROC')

		ENTRY(TABLE.PROC_PTR)

		HOLD;

...

The code fragment in CODE EXAMPLE 6-2 fetches the procedure pointer from TABLE, calls KXSYM2FUNC to map it into the current Sun MTP transaction server process' address space, then invokes the procedure.

	...

DCL KXSYM2FUNC        ENTRY(POINTER VALUE) RETURNS(POINTER)

                      EXTERNAL('kxsym2func');

DCL NULL              BUILTIN;

DCL PROC              ENTRY VARIABLE;

DCL 1     PROC_OVERLAY       DEFINED(PROC),

          2 ENTRY_PTR        POINTER,

          2 DISPLAY_PTR      FIXED BIN(31);

          ...

PROC_OVERLAY.ENTRY_PTR   = KXSYM2FUNC(TABLE.PROC_PTR);

PROC_OVERLAY.DISPLAY_PTR = 0;

IF PROC_OVERLAY.ENTRY_PTR = NULL THEN

	/*

	*  Error! Was there a corresponding LOAD?

	*         Did a condition occur during that LOAD?

	*

	*/

	...

ELSE

	CALL PROC;

	...

---

Using CEMT With Shared Libraries

The options to CEMT SET and CEMT INQ enable you to dynamically change the shared library for a program and to inquire about the name of the current library. See Running a Different Version of the Same Shared Library.

The LIBRARY option to the CEMT SET PROGRAM transaction enables you to dynamically change a program's shared library while the region is running.

Format:

CEMT S[ET] PROG[RAM] prog-name LIB[RARY] lib-name PROG[RAM] prog-name 	LIB[RARY] blankreset

where:

After you execute the CEMT command, you must execute a CINI transaction to initialize the new shared library and internal tables.

Use the LIBRARY option of the CEMT INQ PROGRAM transaction to inquire for the name of the current shared library.

Format:

CEMT I[NQ] PROG[RAM] prog-name LIB[RARY]

prog-name is the name of the program, a maximum of eight characters.

If the program has a shared library, the following message is displayed:

KIX1584I CEMT transaction terminated ShrLib = lib-name

If the program does not have a shared library, the following message is displayed:

KIX1584I CEMT transaction terminated ShrLib = NoSharedLibPrsnt

Running a Different Version of the Same Shared Library

Sun MTP enables you to load a new version of a shared library without having to recycle the region. For example, your application uses a shared library named prog_pay1.so, which is defined in the PPT as dir1/prog_pay1. During execution, you observe that prog_pay1.so does not behave as expected, so you compile and rebuild a new version of prog_pay1.so. Rather than recycling the region to pick up the new version, save the new version of the shared library in a different directory, dir2.

To run the new shared library, use the following transactions:

CEMT SET PROGRAM MY_PROG1 LIBRARY dir2/prog_pay1

This transaction changes the shared memory PPT to point to the new directory where the shared library is located. This change is valid for the life of the region. The path name can be up to 16 characters long and is relative to the $KIXLIB or $KIXSYS directories. Refer to the Sun Mainframe Transaction Processing Software Reference Guide for information about defining shared libraries in the PPT.

The following transaction causes the transaction processors to reopen the shared libraries and make them available.

CEMT SET PROGRAM MY_PROG1 LIBRARY NEWCOPY

---

Building Shared Libraries

The makefile in CODE EXAMPLE 6-3 illustrates how to build a shared library. This makefile compiles the PL/I version of the ACCT transaction for the sample Account application provided by Liant. Refer to the Sun Mainframe Transaction Processing Software Installation Guide for directions to run this application.

When using the sample makefile:

• The -pic (position independent code) compiler option must be used.
• The -zp1 compiler option causes all structures to be mapped as if the UNALIGNED attribute were specified at level one of each structure. The layout of the data files determines if this option is necessary.
• Each main program is linked into its own shared library: acct00.so, acct01.so, acct02.so, acct03.so, and acct04.so.
• All common subroutines are linked into one or more shared libraries, and these libraries, together with the Open PL/I runtime libraries, are linked into the transaction server. In the Account example there is only one common subroutine, ALPHANUM, which is linked into the shared library libacct.so.

CODE EXAMPLE 6-3 makefile for Building Shared Libraries (1 of 3)

INCPATH = $(LPI_PRODUCT_DIR)/include:$(PROJECT)/inc:$(PROJECT)/maps   # Use these options to debug an application with CodeWatch #PPFLAGS = -nodebuginfo -isuffix .inc -ipath $(INCPATH) #PLIFLAGS = -zp1 -debug -opt 2 -pic -ipath $(INCPATH) #PLTFLAGS = -cicsdebug   PPFLAGS = -isuffix .inc -ipath $(INCPATH) PLIFLAGS = -zp1 -opt 3 -pic -ipath $(INCPATH) PLTFLAGS =   # Solaris values SHLIB_SUFFIX = .so SHLIB_LDFLAG = -G   .SUFFIXES: .o .pli .plt   .plt.o: $(PP) $(PPFLAGS) $< -o temp.plt $(PLT) $(PLTFLAGS) -i temp.plt -o $*.temppli $(PLI) $(PLIFLAGS) $*.temppli -o $*.o -rm temp.plt   .pli.o: $(PP) $(PPFLAGS) $< -o $*.temppli $(PLI) $(PLIFLAGS) $*.temppli   LIBACCT_OBJECTS = ALPHANUM.o all: maps kixlib unikixtran   clean: rm -f *.list *.o *.stb *.temppli temp.plt deinstall: rm -f $(KIXLIB)/acct00.so rm -f $(KIXLIB)/acct01.so rm -f $(KIXLIB)/acct02.so rm -f $(KIXLIB)/acct03.so rm -f $(KIXLIB)/acct04.so rm -f $(KIXLIB)/debug.so rm -f $(KIXLIB)/libacct$(SHLIB_SUFFIX)   install: mv acct00.so $(KIXLIB) mv acct01.so $(KIXLIB) mv acct02.so $(KIXLIB) mv acct03.so $(KIXLIB) mv acct04.so $(KIXLIB) mv debug.so $(KIXLIB) mv libacct$(SHLIB_SUFFIX) $(KIXLIB)   kixlib: acct00 acct01 acct02 acct03 acct04 debug libacct install   maps: cd $(KIXMAPS); $(MAKE) maps   unikixtran: cd $(KIXBIN); $(MAKE) unikixtran   acct00: ACCT00.o ld $(SHLIB_LDFLAG) -o $@.so ACCT00.o   acct01: ACCT01.o ALPHANUM.o ld $(SHLIB_LDFLAG) -o $@.so ACCT01.o   acct02: ACCT02.o ALPHANUM.o ld $(SHLIB_LDFLAG) -o $@.so ACCT02.o   acct03: ACCT03.o ld $(SHLIB_LDFLAG) -o $@.so ACCT03.o   acct04: ACCT04.o ld $(SHLIB_LDFLAG) -o $@.so ACCT04.o   debug: debug.o ld $(SHLIB_LDFLAG) -o $@.so $@.o   libacct: $(LIBACCT_OBJECTS) ld $(SHLIB_LDFLAG) -o $@$(SHLIB_SUFFIX) $(LIBACCT_OBJECTS)   ACCT01.o: $(PROJECT)/maps/ACCTSET.inc ACCT01.o: $(PROJECT)/inc/ACCTREC.inc ACCT01.o: $(PROJECT)/inc/ACIXREC.inc ACCT01.o: $(PROJECT)/inc/ALPHANUM.dcl ACCT02.o: $(PROJECT)/inc/ACCTREC.inc ACCT02.o: $(PROJECT)/maps/ACCTSET.inc ACCT02.o: $(PROJECT)/inc/ACIXREC.inc ACCT02.o: $(PROJECT)/inc/ALPHANUM.dcl ACCT03.o: $(PROJECT)/maps/ACCTSET.inc ACCT04.o: $(PROJECT)/maps/ACCTSET.inc

Sun Mainframe Transaction Processing Software Developer's Guide

816-5329-11

Copyright © 2004, Sun Microsystems, Inc. All rights reserved.