BEA Tuxedo. Using the BEA Tuxedo Workstation Component

Transcription

1 BEA Tuxedo Usig the BEA Tuxedo Workstatio Compoet BEA Tuxedo Release 7.1 Documet Editio 7.1 May 2000

2 Copyright Copyright 2000 BEA Systems, Ic. All Rights Reserved. Restricted Rights Leged This software ad documetatio is subject to ad made available oly pursuat to the terms of the BEA Systems Licese Agreemet ad may be used or copied oly i accordace with the terms of that agreemet. It is agaist the law to copy the software except as specifically allowed i the agreemet. This documet may ot, i whole or i part, be copied photocopied, reproduced, traslated, or reduced to ay electroic medium or machie readable form without prior coset, i writig, from BEA Systems, Ic. Use, duplicatio or disclosure by the U.S. Govermet is subject to restrictios set forth i the BEA Systems Licese Agreemet ad i subparagraph (c)(1) of the Commercial Computer Software-Restricted Rights Clause at FAR ; subparagraph (c)(1)(ii) of the Rights i Techical Data ad Computer Software clause at DFARS , subparagraph (d) of the Commercial Computer Software--Licesig clause at NASA FAR supplemet ; or their equivalet. Iformatio i this documet is subject to chage without otice ad does ot represet a commitmet o the part of BEA Systems. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. FURTHER, BEA Systems DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE, OR THE RESULTS OF THE USE, OF THE SOFTWARE OR WRITTEN MATERIAL IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. Trademarks or Service Marks BEA, ObjectBroker, TOP END, ad Tuxedo are registered trademarks of BEA Systems, Ic. BEA Builder, BEA Coect, BEA Maager, BEA MessageQ, BEA Jolt, M3, esolutios, elik, WebLogic, ad WebLogic Eterprise are trademarks of BEA Systems, Ic. All other compay ames may be trademarks of the respective compaies with which they are associated. Usig the BEA Tuxedo Workstatio Compoet Documet Editio Date Software Versio 7.1 May 2000 BEA Tuxedo Release 7.1

3 Cotets What You Need to Kow...v e-docs Web Site... vi How to Prit the Documet... vi Documetatio Covetios... vii 1. Overview of Workstatio What Is the BEA Tuxedo Workstatio Compoet Limitatios of Workstatio Cliets Workstatio Admiistratio Usig the Workstatio Compoet Writig Cliet Programs Iteroperability Restrictios for Workstatio Cliets Buildig Cliet Programs Usig BEA Tuxedo System-supplied Cliets Usig wud i a Security Applicatio Ruig BEA Tuxedo System Cliets o a Workstatio Verifyig the Directory Structure o Workstatio Cliets Settig Eviromet Variables Creatig a Eviromet File Usig tuxreadev How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio Workstatio for Widows Beefits of Usig Workstatio o a Widows Platform Software Prerequisites Writig Cliet Programs Usig the BEA Tuxedo Workstatio Compoet iii

4 Iteroperability Restrictios for Workstatio Cliets Buildig Cliet Programs Rutime Limitatios How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio Brigig Up bakapp o Workstatios Characteristics of a Workstatio Applicatio Brigig Up bakapp o a Workstatio Cliet Chages o the Native Site Editig the Cofiguratio File Loadig ad Bootig the Cofiguratio Settig the bakapp Variables Buildig the bakapp Cliet Ruig the bakapp Cliet iv Usig the BEA Tuxedo Workstatio Compoet

5 About This Documet This documet explais what the BEA Tuxedo Workstatio compoet is, how to use the Workstatio compoet i UNIX ad Widows eviromets, ad how to brig up the bakapp sample applicatio o a workstatio. This documet covers the followig topics: Chapter 1, Overview of Workstatio, provides a brief overview of the workstatio compoet. Chapter 2, Usig the Workstatio Compoet, provides iformatio o writig workstatio cliet programs, usig BEA Tuxedo System-supplied cliets, ad ruig BEA Tuxedo system cliets o a workstatio. Chapter 3, Workstatio for Widows, describes the use of the BEA Tuxedo Workstatio for Widows platforms. Chapter 4, Brigig Up bakapp o Workstatios, describes the steps to follow i brigig up bakapp, the BEA Tuxedo system sample applicatio, o a UNIX or Widows workstatio. What You Need to Kow This documet is iteded maily for applicatio developers who are iterested i usig the Workstatio compoet i their applicatios. It provides a overview of the Workstatio compoet, how to write ad build cliet programs usig the Workstatio compoet, ad how to brig up the bakapp applicatio o a workstatio. Usig the BEA Tuxedo Workstatio Compoet v

6 e-docs Web Site BEA product documetatio is available o the BEA corporate Web site. From the BEA Home page, click o Product Documetatio or go directly to the e-docs Product Documetatio page at How to Prit the Documet You ca prit a copy of this documet from a Web browser, oe file at a time, by usig the File >Prit optio o your Web browser. A PDF versio of this documet is available o the BEA Tuxedo documetatio Home page o the e-docs Web site (ad also o the documetatio CD). You ca ope the PDF i Adobe Acrobat Reader ad prit the etire documet (or a portio of it) i book format. To access the PDFs, ope the BEA Tuxedo documetatio Home page, click the PDF files butto ad select the documet you wat to prit. If you do ot have the Adobe Acrobat Reader, you ca get it for free from the Adobe Web site at Cotact Us! Your feedback o the BEA Tuxedo documetatio is importat to us. Sed us at docsupport@bea.com if you have questios or commets. Your commets will be reviewed directly by the BEA professioals who create ad update the BEA Tuxedo documetatio. I your message, please idicate that you are usig the documetatio for the BEA Tuxedo 7.1 release. vi Usig the BEA Tuxedo Workstatio Compoet

7 Documetatio Covetios If you have ay questios about this versio of BEA Tuxedo, or if you have problems istallig ad ruig BEA Tuxedo, cotact BEA Customer Support through BEA WebSupport at You ca also cotact Customer Support by usig the cotact iformatio provided o the Customer Support Card, which is icluded i the product package. Whe cotactig Customer Support, be prepared to provide the followig iformatio: Your ame, address, phoe umber, ad fax umber Your compay ame ad compay address Your machie type ad authorizatio codes The ame ad versio of the product you are usig A descriptio of the problem ad the cotet of pertiet error messages Documetatio Covetios The followig documetatio covetios are used throughout this documet. Covetio boldface text Ctrl+Tab italics Item Idicates terms defied i the glossary. Idicates that you must press two or more keys simultaeously. Idicates emphasis or book titles. Usig the BEA Tuxedo Workstatio Compoet vii

8 Covetio moospace text moospace boldface text moospace italic text UPPERCASE TEXT Item Idicates code samples, commads ad their optios, data structures ad their members, data types, directories, ad file ames ad their extesios. Moospace text also idicates text that you must eter from the keyboard. Examples: #iclude <iostream.h> void mai ( ) the poiter psz chmod u+w * \tux\data\ap.doc tux.doc BITMAP float Idetifies sigificat words i code. Example: void commit ( ) Idetifies variables i code. Example: Strig expr Idicates device ames, eviromet variables, ad logical operators. Examples: LPT1 SIGNON OR { } Idicates a set of choices i a sytax lie. The braces themselves should ever be typed. [ ] Idicates optioal items i a sytax lie. The brackets themselves should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list]... Separates mutually exclusive choices i a sytax lie. The symbol itself should ever be typed. viii Usig the BEA Tuxedo Workstatio Compoet

9 Documetatio Covetios Covetio Item... Idicates oe of the followig i a commad lie: That a argumet ca be repeated several times i a commad lie That the statemet omits additioal optioal argumets That you ca eter additioal parameters, values, or other iformatio The ellipsis itself should ever be typed. Example: buildobjcliet [-v] [-o ame ] [-f file-list]... [-l file-list] Idicates the omissio of items from a code example or from a sytax lie. The vertical ellipsis itself should ever be typed. Usig the BEA Tuxedo Workstatio Compoet ix

10 x Usig the BEA Tuxedo Workstatio Compoet

11 CHAPTER 1 Overview of Workstatio What Is the BEA Tuxedo Workstatio Compoet Workstatio Admiistratio What Is the BEA Tuxedo Workstatio Compoet The Workstatio compoet of the BEA Tuxedo system allows applicatio cliets to reside o a machie that does ot have a full server-side istallatio, that is, a machie that does ot support ay admiistratio or applicatio servers. All commuicatio betwee the cliet ad the applicatio servers takes place over the etwork. A Workstatio cliet process ca ru o a Widows or UNIX platform. The cliet has access to the ATMI. The etworkig behid requests is trasparet to the user. A Workstatio cliet does ot have access to all the capabilities available to a ative cliet. Both types of cliets, however, ca do the followig: Sed ad receive messages Begi, ed, or commit trasactios Sed ad receive usolicited messages Meet applicatio security requiremets Usig the BEA Tuxedo Workstatio Compoet 1-1

12 1 Overview of Workstatio Commuicate iformatio about remote cliets through the tmadmi(1) commad Note: A Workstatio cliet commuicates with applicatio servers through a Workstatio Hadler (WSH) process. Limitatios of Workstatio Cliets Workstatio cliets do ot have access to all the fuctioality available to ative cliets. For example, ulike a ative cliet, a Workstatio cliet caot joi a applicatio as tpsysadm, which meas that the cliet caot subsequetly subscribe to a evet that issues a service call. See Also Workstatio Coectivity: Usig BEA Tuxedo Workstatio o page 4-26 i Itroducig the BEA Tuxedo System What Are the Workstatio Hadler ad Workstatio Listeer o page 3-62 i Itroducig the BEA Tuxedo System About Workstatio Cliets o page 9-1 i Settig Up a BEA Tuxedo Applicatio Workstatio Admiistratio To itegrate a workstatio cliet ito a BEA Tuxedo applicatio, you must defie ay required ad desired parameters for that cliet i the applicatio cofiguratio file. See Settig Up Workstatio Cliets o page 10-1 i Settig Up a BEA Tuxedo Applicatio for details. 1-2 Usig the BEA Tuxedo Workstatio Compoet

13 Workstatio Admiistratio See Also buildwsh(1) i BEA Tuxedo Commad Referece WSL(5) i BEA Tuxedo File Formats ad Data Descriptios Referece Usig the BEA Tuxedo Workstatio Compoet 1-3

14 1 Overview of Workstatio 1-4 Usig the BEA Tuxedo Workstatio Compoet

15 CHAPTER 2 Usig the Workstatio Compoet Writig Cliet Programs Usig BEA Tuxedo System-supplied Cliets Ruig BEA Tuxedo System Cliets o a Workstatio How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio Writig Cliet Programs You ca develop cliet programs targeted for workstatios i the same way that you would develop cliet programs withi the BEA Tuxedo system admiistrative domai (that is, ative cliets). All of the ATMI ad FML fuctios are available to the Workstatio cliet. Iteroperability Restrictios for Workstatio Cliets Iteroperability betwee BEA Tuxedo Release 7.1 Workstatio cliets ad applicatios based o pre-7.1 releases of the BEA Tuxedo system is supported i ay of the followig situatios: The cliet is either multithreaded or multicotexted. Usig the BEA Tuxedo Workstatio Compoet 2-1

16 2 Usig the Workstatio Compoet The cliet is multicotexted. The cliet is multithreaded ad each thread is i a differet cotext A BEA Tuxedo Release 7.1 Workstatio cliet with multiple threads i a sigle cotext caot iteroperate with a pre-7.1 release of the BEA Tuxedo system. Buildig Cliet Programs You compile ad lik-edit Workstatio cliet programs usig the buildcliet(1) commad. If you are buildig a Workstatio cliet o a ative ode (that is, oe o which the complete BEA Tuxedo system is istalled), use the -w optio to idicate the cliet should be built usig the workstatio libraries. Otherwise, o a ative ode, where both ative ad workstatio libraries are preset, the default is to use the ative libraries. I this case, usig the -w optio esures that the correct libraries for a workstatio cliet are used. O a workstatio, where oly the workstatio libraries are preset, it is ot ecessary to use the -w optio. The followig listig shows a example of the buildcliet(1) commad lie o a ative ode. Listig 2-1 buildcliet Commad Lie TUXDIR=/var/opt/tuxedo CC=cc; export TUXDIR CC buildcliet -w -o wsclt -f wsclt.c -f userlib1.a userlib2.a The -o optio provides a ame for your output file. Iput files are specified with the -f firstfiles optio to idicate that they are lik-edited before system libraries. As idicated i the example, you must defie the TUXDIR eviromet variable to esure that the buildcliet commad ca locate system libraries. CC defaults to cc but ca be set to aother compiler, as show i the example. 2-2 Usig the BEA Tuxedo Workstatio Compoet

17 Usig BEA Tuxedo System-supplied Cliets See Also Writig Cliets o page 4-1 i Programmig a BEA Tuxedo Applicatio Usig C ad Programmig a BEA Tuxedo Applicatio Usig COBOL COBOL Laguage Bidigs for the Workstatio Compoet o page 12-1 i Programmig a BEA Tuxedo Applicatio Usig COBOL Writig Security Code So Cliet Programs Ca Joi the Applicatio o page 3-4 i Usig BEA Tuxedo Security buildcliet(1) i BEA Tuxedo Commad Referece Usig BEA Tuxedo System-supplied Cliets wud ad wud32 are BEA Tuxedo system-supplied driver programs provided for workstatios. These driver programs are based o the stadard BEA Tuxedo cliet programs, ud ad ud32, that have bee built usig the Workstatio libraries. Use wud(1) to sed FML buffers to BEA Tuxedo system servers. Use wud32 with fielded FML32 buffers of type FBFR32. Usig wud i a Security Applicatio If wud is ru i a security applicatio, it requires a applicatio password to access the applicatio. If stadard iput is from a termial, wud prompts the user for a applicatio password. If you are ruig the cliet program from a script, which is a commo occurrece with wud, the password is retrieved from the eviromet variable APP_PW. If this eviromet variable is ot specified ad a applicatio password is required, the wud fails. Do ot cofuse the APP_PW eviromet variable with the similar cofiguratio file parameter, SECURITY, for which the value APP_PW eables the security feature. Usig the BEA Tuxedo Workstatio Compoet 2-3

18 2 Usig the Workstatio Compoet See Also ud, wud(1) i BEA Tuxedo Commad Referece Ruig BEA Tuxedo System Cliets o a Workstatio After the cliet programs have bee developed ad tested, they ca be moved to the workstatios where they will be available to users. Verifyig the Directory Structure o Workstatio Cliets The followig table describes the directory structure o a Workstatio cliet after you have istalled the Workstatio compoet of the BEA Tuxedo system. UNIX Directory Widows Directory Descriptio $APPDIR %APPDIR% Cotais the cliet executables. These executables are commoly kept i the directory from which the applicatio is ru. $TUXDIR/bi %TUXDIR%\bi Cotais BEA Tuxedo system commads ad system cliets such as wud. $TUXDIR/cobiclude %TUXDIR%\cobiclude Cotais copylib etries for use i COBOL programs. $TUXDIR/iclude %TUXDIR%\iclude Cotais BEA Tuxedo system header files such as atmi.h. $TUXDIR/lib %TUXDIR%\lib Cotais rutime libraries. $TUXDIR/locale/C %TUXDIR%\locale\C Cotais message catalogs for the default locale (U.S. Eglish). 2-4 Usig the BEA Tuxedo Workstatio Compoet

19 Ruig BEA Tuxedo System Cliets o a Workstatio UNIX Directory Widows Directory Descriptio $TUXDIR/samples %TUXDIR%\samples Cotais several subdirectories with sample applicatios. Settig Eviromet Variables Workstatio cliets make use of several eviromet variables. The followig table shows the eviromet variables that are checked by tpiit(3c) or TPINITIALIZE(3cbl) whe the workstatio cliet attempts to joi the applicatio. See Defiig Workstatio Cliets o page 10-1 i Settig Up a BEA Tuxedo Applicatio for details o settig these eviromet variables. Eviromet Variable WSALLOWPRE71 WSBUFFERS WSDEVICE WSENVFILE WSFADDR WSFRANGE Descriptio Determies whether the workstatio machie ruig BEA Tuxedo 7.1 or later software is allowed to iteroperate with pre-release 7.1 BEA Tuxedo applicatios. Settig the variable to Y (WSALLOWPRE71=Y) allows iteroperability. The umber of packets per applicatio. Device ame to be used to access the etwork. This variable is oly required whe the BEA Tuxedo system is usig the TLI etworkig iterface. Name of a file cotaiig eviromet variable settigs to be set i the cliet s eviromet. The etwork address used by the workstatio cliet whe coectig to the workstatio listeer or workstatio hadler. This variable, alog with the WSFRANGE variable, determies the rage of TCP/IP ports to which a workstatio cliet will attempt to bid before makig a outboud coectio. This address must be a TCP/IP address. The rage of TCP/IP ports to which a workstatio cliet process attempts to bid before makig a outboud coectio. The WSFADDR parameter specifies the base address of the rage. The default is 1. Usig the BEA Tuxedo Workstatio Compoet 2-5

20 2 Usig the Workstatio Compoet Eviromet Variable WSNADDR WSRPLYMAX WSTYPE Descriptio The etwork address of the workstatio listeer (WSL) process through which cliets gai access to the applicatio. Use the value specified i the applicatio cofiguratio file for the workstatio listeer to be called. If the value begis with the characters 0x, the system iterprets it as a strig of hexadecimal digits; otherwise, the system iterprets it as ASCII characters. Maximum amout of core memory that ATMI fuctios use for bufferig applicatio replies before they are dumped to disk. Used by tpiit(3c) ad TPINITIALIZE(3cbl). Replies obtaied usig tpgetrply(3c), TPGETRPLY(3cbl), ad usolicited messages are buffered i this area. Whe this area is filled with oe or more messages, the overflow is writte to a disk file. The system default limit is 256,000 bytes. Whether you use WSRPLYMAX to set a lower limit depeds o the amout of available memory o your machie. Writig replies to disk causes a substatial reductio i performace. Workstatio type. Used withi tpiit(3c) ad TPINITIALIZE(3cbl) whe ivoked by a workstatio cliet to egotiate ecode/decode resposibilities with the ative site. If you do ot specify WSTYPE, the system performs ecodig, eve if it is also uspecified o the ative site.you must explicitly specify the same WSTYPE value for both sites to esure that the ecode/decode feature is tured off. Other eviromet variables may be eeded by Workstatio cliets o a UNIX workstatio depedig o the BEA Tuxedo system features beig used. The compilatio(5) referece page i BEA Tuxedo File Formats ad Data Descriptios Referece explais which variables are eeded uder what circumstaces. Creatig a Eviromet File If you have created a eviromet file, it is read whe tpiit(3c) or TPINITIALIZE(3cbl) is called. The followig listig shows a sample file that could be used for two differet applicatios. 2-6 Usig the BEA Tuxedo Workstatio Compoet

21 Ruig BEA Tuxedo System Cliets o a Workstatio Listig 2-2 Eviromet File TUXDIR=/opt/tuxedo [applicatio1] ;this is a commet /* this is a commet */ #this is a commet //this is a commet set FIELDTBLS=app1_flds set FLDTBLDIR=/opt/app1/udataobj [applicatio2] FIELDTBLS=app2_flds FLDTBLDIR=/opt/app2/udataobj The format of the file is as follows: Ay leadig space ad tab characters o each lie are igored ad are ot cosidered i the followig poits. Lies cotaiig variables to be put ito the eviromet are of the followig form: variable=value or set variable=value where variable must begi with a alphabetic or uderscore character ad cotai oly alphaumeric or uderscore characters, ad value may cotai ay character except ewlie. Withi the value, strigs of the form ${ev} are expaded usig variables already i the eviromet. Forward referecig is ot supported ad if a value is ot set, the variable is replaced with the empty strig. Backslash (\) may be used to escape the dollar sig ad itself. All other shell quotig ad escape mechaisms are igored ad the expaded value is placed ito the eviromet. Lies begiig with slash (/), poud sig (#), or exclamatio poit (!) are treated as commets ad igored. Lies begiig with other characters besides these commet characters, a left square bracket, or a alphabetic or uderscore character are reserved for future use; their use is udefied. The file is partitioed ito sectios by lies of the form [label] Usig the BEA Tuxedo Workstatio Compoet 2-7

22 2 Usig the Workstatio Compoet where label is the ame of the sectio ad follows the same rules for variable above. The label is siletly trucated if loger tha 31 characters. Variable lies betwee the top of the file ad the first label are put ito the eviromet for all applicatios; this is the global sectio. A label of [] also idicates the global sectio. Other variables are put ito the eviromet oly if the label matches the applicatio label specified for the applicatio. Usig tuxreadev Whe you call the tuxreadev(3c) fuctio, it reads the eviromet file ad adds the eviromet variables to the eviromet for the etire process, idepedet of platform. These variables are available usig tuxgetev(3c) ad ca be reset usig tuxputev(3c). void tuxreadev(char *file, char *label) If file is NULL, the a default file ame is used. The default file ames for various platforms are as follows: Widows: %TUXDIR%\TUXEDO.ENV UNIX: $TUXDIR/TUXEDO.ev If the value of label is NULL, the oly variables i the global sectio are put ito the eviromet. For other values of label, the global sectio variables plus ay variables i a sectio matchig the label are put ito the eviromet. A error message is prited to the userlog uder the followig coditios: a memory failure a o-ull file ame does ot exist a o-ull label does ot exist Each time tpiit(3c)is called (either explicitly or implicitly by callig aother ATMI fuctio), tuxreadev(3c) is called automatically i Workstatio cliets. If WSENVFILE is set i the eviromet, the it desigates the eviromet file; otherwise, NULL is passed to tuxreadev() for the file ame so that the default file 2-8 Usig the BEA Tuxedo Workstatio Compoet

23 How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio is used. If WSAPP is set i the eviromet, the it is to be used as the sectio label i the eviromet file; otherwise, NULL is passed to tuxreadev() for the label ame. Applicatio cliets may also call tuxreadev() explicitly. The eviromet is implemeted ad available i differet ways o differet platforms. A uiform iterface to the eviromet is provided via the existig tuxgetev(3c) ad tuxputev(3c) fuctios. These fuctios provide access to the followig: All variables from the specified WSENVFILE file for the specified WSAPP label (or the defaults if ot specified) The eviromet variables i the operatig system eviromet See Also tpiit(3c) i BEA Tuxedo C Fuctio Referece tuxreadev(3c) i BEA Tuxedo C Fuctio Referece How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio To joi a BEA Tuxedo applicatio, a multithreaded workstatio cliet must always call tpiit() with the TPMULTICONTEXTS flag set, eve if the cliet is ruig i sigle-cotext mode. See Also tpiit(3c) i BEA Tuxedo C Fuctio Referece Usig the BEA Tuxedo Workstatio Compoet 2-9

24 2 Usig the Workstatio Compoet 2-10 Usig the BEA Tuxedo Workstatio Compoet

25 CHAPTER 3 Workstatio for Widows Beefits of Usig Workstatio o a Widows Platform Software Prerequisites Writig Cliet Programs How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio Beefits of Usig Workstatio o a Widows Platform The Widows istatiatio of Workstatio offers sigificat beefits to applicatio developers: Executable text is shared amog applicatios, savig memory. BEA Tuxedo Workstatio upgrades are possible without relikig or modifyig a applicatio program s executable file. Dyamic likig permits iterpretive graphical applicatio geerator tools (such as Visual Basic, ObjectVisio ad SQLWidows) to call BEA Tuxedo system services. Note: All refereces to Widows apply to Widows 95, Widows 98, ad Widows NT. Usig the BEA Tuxedo Workstatio Compoet 3-1

26 3 Workstatio for Widows Software Prerequisites The software prerequisites for ruig the Workstatio compoet for Widows are as follows: Workstatio for Widows rus uder the Widows 95, Widows 98 ad Widows NT operatig systems. I Widows, the ative TCP/IP stack is used. I Widows, while usig TCP/IP ay Widows Sockets Compliat TCP/IP stack ca be used. The server machie must have the BEA Tuxedo system ad the ative-side BEA Tuxedo Workstatio istalled. Writig Cliet Programs You ca develop cliet programs targeted for Widows workstatios i the same way that you would develop ative cliet programs withi the BEA Tuxedo system admiistrative domai. All of the ATMI fuctios are available. Iteroperability Restrictios for Workstatio Cliets Iteroperability betwee BEA Tuxedo Release 7.1 Workstatio cliets ad applicatios based o pre-7.1 releases of the BEA Tuxedo system is supported i ay of the followig situatios: The cliet is either multithreaded or multicotexted. The cliet is multicotexted. The cliet is multithreaded ad each thread is i a differet cotext 3-2 Usig the BEA Tuxedo Workstatio Compoet

27 Writig Cliet Programs A BEA Tuxedo Release 7.1 Workstatio cliet with multiple threads i a sigle cotext caot iteroperate with a pre-7.1 release of the BEA Tuxedo system. Buildig Cliet Programs To compile cliet programs writte i C, you ca use ay compiler that ca read Microsoft C import libraries. To compile COBOL source programs that call the ATMI, use the LITLINK optio of the COBOL compiler. For details, see COBOL Laguage Bidigs for the Workstatio Compoet o page 12-1 i Programmig a BEA Tuxedo Applicatio Usig COBOL. Use buildcliet(1) with the -w flag to lik-edit your cliet programs. You ca also build BEA Tuxedo cliets without usig the buildcliet(1) utility. If you are usig Microsoft Visual C++ projects, use the followig settigs: Set the Preprocessor optio to -DWIN32 Add WTUXWS32.LIB MSVCRT.LIB to the iput libraries for the liker optio. I additio, set the INCLUDE, LIB, ad PATH search directories appropriately. Rutime Whe you ru cliet programs, your PATH must iclude %TUXDIR%\bi. Limitatios The BEA Tuxedo libraries (DLLs) prior to BEA Tuxedo Release 7.1 are ot thread-safe. For applicatios writte usig the pre-release 7.1 DLLs, threads should ot be used; otherwise, threaded access is serialized through all BEA Tuxedo calls (such as ATMI, FML, userlog(), ad so o). See Also Writig Cliets o page 4-1 i Programmig a BEA Tuxedo Applicatio Usig C or Programmig a BEA Tuxedo Applicatio Usig COBOL Usig the BEA Tuxedo Workstatio Compoet 3-3

28 3 Workstatio for Widows COBOL Laguage Bidigs for the Workstatio Compoet o page 12-1 i Programmig a BEA Tuxedo Applicatio Usig COBOL Writig Security Code So Cliet Programs Ca Joi the Applicatio o page 3-4 i Usig BEA Tuxedo Security buildcliet(1) i BEA Tuxedo Commad Referece How a Multithreaded or Multicotexted Workstatio Cliet Jois a Applicatio To joi a BEA Tuxedo applicatio, a multithreaded workstatio cliet must always call tpiit(3c) with the TPMULTICONTEXTS flag set, eve if the cliet is ruig i sigle-cotext mode. See Also tpiit(3c) i BEA Tuxedo C Fuctio Referece 3-4 Usig the BEA Tuxedo Workstatio Compoet

29 CHAPTER 4 Brigig Up bakapp o Workstatios Characteristics of a Workstatio Applicatio Brigig Up bakapp o a Workstatio Cliet Chages o the Native Site Settig the bakapp Variables Buildig the bakapp Cliet Ruig the bakapp Cliet Characteristics of a Workstatio Applicatio I a workstatio applicatio, cliet processes are moved off the ative site. The listeer process (WSL) rus with a well-kow etwork address ad starts surrogate workstatio hadlers (WSH) as eeded. Servers ru o oe or more machies withi the BEA Tuxedo admiistrative domai. Existig servers are available to ru o the BEA Tuxedo system odes i either sigle processor (SHM) or multiprocessor (MP) mode. O Workstatios, the sample applicatios are located i the followig directories: $TUXDIR/samples/atmi/bakapp (UNIX) %TUXDIR%\samples\atmi\bakapp (Widows) Usig the BEA Tuxedo Workstatio Compoet 4-1

30 4 Brigig Up bakapp o Workstatios Brigig Up bakapp o a Workstatio Cliet The followig illustratio shows the steps i the process of brigig up bakapp o a Workstatio cliet. Figure 4-1 Steps i brigig up bakapp Chages o the Native Site Istall ad build the bakapp software o the ative site. The procedure for doig this is described i Tutorial for bakapp, a Full C Applicatio o page 3-1 i Tutorials for Developig a BEA Tuxedo Applicatio ad i the followig README files o the master machie where your BEA Tuxedo system software is istalled: 4-2 Usig the BEA Tuxedo Workstatio Compoet

31 Chages o the Native Site $TUXDIR/samples/atmi/bakapp/README (o UNIX systems) %TUXDIR%\samples\atmi\bakapp\README.t (o Widows systems) Editig the Cofiguratio File *MACHINES DEFAULT: MAXWSCLIENTS=50 # *GROUPS You eed to edit the cofiguratio file you pla to use (either ubbshm or ubbmp) to specify the workstatio listeer (WSL) as a server i the GROUPS ad SERVERS sectios, ad to specify MAXWSCLIENTS i the MACHINES sectio. Whe you edit the GROUPS sectio, put the etry for WSGRP ahead of the DEFAULT lie or move the specificatios for TMSNAME ad TMSCOUNT to the server groups that use them; they should ot be assiged to WSGRP. The ew specificatios should be i the followig format. WSGRP # *SERVERS GRPNO=<ext available group #> LMID=SITE1 WSL SRVGRP=WSGRP SRVID=1 CLOPT= -A - //machie:port -m 1 -M 5 -x 10" Also, remember to icrease the MAXACCESSERS parameter i the RESOURCES or MACHINES sectio to cover the ew workstatio cliets. Loadig ad Bootig the Cofiguratio Before you ca start usig a Workstatio cliet, you eed to ru tmloadcf(1) to load the cofiguratio file ito its biary form ad tmboot(1) to start the applicatio. These commads do ot have to be ru immediately; there is work to be doe i gettig the bakapp cliets istalled o your workstatios ad gettig them built. However, the applicatio must be ruig o the BEA Tuxedo system ative site whe you attempt to joi the applicatio from a workstatio. The steps for loadig ad bootig Usig the BEA Tuxedo Workstatio Compoet 4-3

32 4 Brigig Up bakapp o Workstatios bakapp o the ative site are part of the overall procedure documeted i Tutorial for bakapp, a Full C Applicatio o page 3-1i Tutorials for Developig a BEA Tuxedo Applicatio. See Also tmloadcf(1) i BEA Tuxedo Commad Referece WSL(5) i BEA Tuxedo File Formats ad Data Descriptios Referece Tutorial for bakapp, a Full C Applicatio o page 3-1 i Tutorials for Developig a BEA Tuxedo Applicatio Defiig a Workstatio Listeer (WSL) as a Server o page 10-4 i Settig Up a BEA Tuxedo Applicatio Settig the bakapp Variables To set your eviromet to ru bakapp, complete the followig procedure o the workstatio cliet. 1. Set the followig eviromet variables. WSNADDR=<WSL advertised address(es)> WSTYPE=<type of Workstatio machie> 2. Iclude $TUXDIR/bi (o UNIX systems) or %TUXDIR%\bi (o Widows systems) i your PATH. 3. Verify that your eviromet is set appropriately to ru the C compiler. 4-4 Usig the BEA Tuxedo Workstatio Compoet

33 Buildig the bakapp Cliet Buildig the bakapp Cliet To build a cliet program, eter the followig commads. mkfldhdr bakflds buildcliet -w -o bakclt -f bakclt.c Ruig the bakapp Cliet To ru the bakapp cliet o the Workstatio, complete the followig procedure. 1. Verify that the value of WSNADDR o the Workstatio cliet matches the value of the CLOPT - optio for the WSL i the SERVERS sectio of the cofiguratio file o the ative site. 2. If bakapp has ot bee booted o the ative site, make sure it has bee booted before you attempt to ru a Workstatio cliet. 3. Execute bakclt to ru the Workstatio cliet. Usig the BEA Tuxedo Workstatio Compoet 4-5

34 4 Brigig Up bakapp o Workstatios 4-6 Usig the BEA Tuxedo Workstatio Compoet