All of the CICS components are declared with the same name, in the z/OS CICS CSD File. All of the resource declarations are made inside a z/OS CICS GROUP named PJ01TERM. This group is declared in the z/OS CICS LIST PJ01LIST used by CICS at start up to be automatically installed.
Table 4‑1 Simple Application Mapsets
Table 4‑2 Simple Application Programs
Table 4‑3 Simple Application Transactions Codes
Table 4‑4 Simple Application VSAM File In our example, all of the UNIX components resulting from platform migration are stored in the trf directory.The COBOL programs and BMS mapsets should be compiled and available as executable modules in the respective directories ${HOME}/trf/cobexe and ${HOME}/trf/MAP_TCP.The ${HOME}/trf/cobexe directory contains the Simple Application CICS executable programs:The ${HOME}/trf/MAP_TCP directory contains the Simple Application Data z/OS BMS mapsets compiled:
•
2. Configure the CICS Runtime Tuxedo Servers Groups and Servers to manage these resources. See Reference for a full description of which configuration files are used with each server.In the following examples using the CICS Simple File-to- Oracle Application, we will use the CICS Runtime Group name SIMPAPP and all our *.desc files will be located in the ${home}/trf/config/resources directory.These declarations are made by filling the transactions.desc file for each transaction you have to implement.In the File-to-Oracle Simple Application example, we have to declare four transactions: SA00, SA01, SA02 and SA03 in the SIMPAPP Group, starting the corresponding COBOL programs RSSAT000, RSSAT001, RSSAT002 and RSSAT003.Listing 4‑1 Simple Application transactions.desc FileAll the programs used by the transactions previously declared, directly or indirectly through EXEC CICS statements like LINK, XCTL, START … must be declared in the same Group.These declarations are made in the programs.desc file for each program to implement.In our Simple Application example, the only programs needed are RSSAT000, RSSAT001, RSSAT002 and RSSAT003 which are all coded in the COBOL languageListing 4‑2 Simple Application programs.desc FileTo converse with end-users thru 3270 terminals or emulators, declare to CICS Runtime all of the physical mapsets (*.mpdef file) used in the COBOL programs previously defined thru the specific EXEC CICS statements described above in this document.These declarations are made by filling the mapsets.desc file for each mapset you have to implement.
1. On the first free physical line, type the [mapset] keyword.
2. On the next line, enter the keyword name= followed by the name of your mapsets.
3. On the next line, enter the keyword filename= followed by the physical path of your physical mapsets (.mpdef file).In our Simple Application example, the mapsets used in our COBOL programs are RSSAM00, RSSAM01, RSSAM02 and RSSAM03.Listing 4‑3 Simple Application mapsets.desc File
Note: The mapsets.desc file does not accept UNIX variables, so a fully expanded path must be provided in this file.
•
• The Simple Application uses only the CUSTOMER Oracle table, resulting from the Oracle Tuxedo Application Rehosting Workbench Data Conversion of the z/OS VSAM KSDS file PJ01AAA.SS.VSAM.CUSTOMER.So, for our File-to-Oracle application example, we have only one accessor, RM_ ODCSF0 (RM for Relational Module), to declare to CICS Runtime.
Note: ODCSF0 represents the logical name previously defined in CICS that pointed to the physical file name PJ01AAA.SS.VSAM.CUSTOMER. Consequently, it is also the only file name known from the CICS COBOL program to access this file by EXEC CICS statements.
2. If the file does not exist, physically create the desc.vsam file at the indicated location.
3. Modify the desc.vsam file by adding a new line describing the different information fields used by the accessor in a "csv" format for each accessor/file used.Listing 4‑4 Simple Application ISAM File Declaration
1.
2. Indicate to CICS Runtime to start only the transactions belonging to the SIMPAPP CICS Runtime Group name.The following example of a *SERVERS section of the Tuxedo ubbconfig file shows the configuration of a ARTSTRN server.Is the Tuxedo Group Name to which ARTSTRN belongs.To be started, the ARTSTRN server must be defined in a Tuxedo Server Group previously defined (and not commented) in the ubbconfig file.Enter the Tuxedo tmadmin psr command to check that all of the CICS Runtime required servers (ARTTCPL, ARTCNX, and ARTSTRN) are running and that their messages conform to the Tuxedo documentation and this document.Another possible check can be made by entering the Tuxedo tmadmin psc command to display all the different Tuxedo Services running.In addition to the CICS Runtime System transactions/services (CSGM, CESN, CESF …), you can now see the transaction codes of your CICS Runtime application SA00, SA01, SA02 and SA03
2. Clear it by pressing the Clear key of your 3270 emulator keypad.
3. Type the main transaction code SA00 (of your CICS Runtime application) in the top left corner:Figure 4‑1 Simple Application transaction Code EntryFigure 4‑2 Simple Application Main MenuAdd the MRM parameter in the group entry of *GROUPS and *RMS section in Tuxedo ubbconfig file. See the following example:Listing 4‑9 Adding MRM Parameter in ubbconfig File ExampleTo build the BDB TMS server, add the following lines to $TUXDIR/udataobj/RM:RBDB02 is the logical file name.On z/OS, this limit cannot be defined in the transaction resource itself but is defined in a distinct resource named TRANCLASS (transaction class) that contains a specific MAXACTIVE parameter describing the maximum number of concurrent instances of the same transaction.To link a transaction to a transaction class, to inherit its parameters, especially the MAXACTIVE parameter, the z/OS CICS transaction resource has a TRANCLASS field containing the name of the TRANCLASS resource.This instance management is performed differently on UNIX with CICS Runtime. The maximum number of transactions running concurrently is defined by the number of servers offering the same transaction. This maximum number and the minimum number are indicated respectively in the MAX and MIN parameters of the ARTSTRN definition in the *SERVERS section of the Tuxedo file ubbconfig.The MAXACTIVE=1 is really an exception in this management because it indicates that no concurrent transaction belonging to these kind of transaction classes can be run simultaneously.All of the transactions linked to transactions classes with a MAXACTIVE superior or equal to 2 are managed by the CICS Runtime Tuxedo Server ARTSTRN and do not required modifying anything else. For the transactions with a MAXACTIVE parameter set to 1, an CICS Runtime Tuxedo Server named ARTSTR1 is dedicated to their specific management.Listing 4‑10 Adding a ARTSTR1 Server to ubbconfig
Note: All of the CICS Runtime Transaction Servers (ARTSTRN, ARTSTR1, ARTATRN and ARTATR1) share the same CICS Runtime Transaction Group Servers, no modifications are required to the ubbconfig Server Group Section (*GROUPS).For ART CICS, concurrent transactions do not really need to be bound to transactions classes with MAXACTIVE parameters superior or equal to two because parallelism is the default behavior.For sequential transactions, it is mandatory because it is the only way to declare these transactions to CICS Runtime. Declare specific transaction classes defined with a MAXACTIVE=1 parameter. Like the other CICS Runtime resources, this one must belong to an CICS Runtime Group name. For each TRANCLASS, declare in a csv format:The first transclass TRCLASS1 has is maxactive parameter equal to 1, indicating that all the transaction belonging to this transclass must be managed sequentially by the ARTSTR1.The two last tranclasses, TRCLASS2 and TRCLASS10, are in fact similar because their maxactive parameters are superior to 1 indicating that the transactions belonging to these tranclasses can run concurrently managed by the ARTSTRN server.Then these transactions must be linked to the following tranclasses that we have previously defined:Once modified, the transactions.desc file will look like this:Listing 4‑11 Example transactions.desc FileSA02;SIMPAPP; Customer Maintenance Screen of the Simple Application;RSSAT002; ; ; ; ; ; ; ; TRCLASS2
• No modification is made to SA00 meaning that no transaction class is associated with this transaction code. It means that this transaction is not associated with a MAXACTIVE=1 parameter and so is not sequential.
• SA02 and SA03 are associated to transaction classes, respectively TRCLASS2 and TRCLASS10, defined with MAXACTIVE >= 2. Knowing that these transactions are not required, the result would be the exactly the same if SA02 and SA03 were defined like SA00 without transaction classes.
• SA01, which can run sequentially, is the only one where the transaction class field is mandatory. Verify that its associated transaction class, TRCLASS1, is really defined with a MAXACTIVE=1.The ARTSTR1, is shown below:These transactions are launched by specifics CICS EXEC CICS START TRANSID requests coded in the CICS programs that are not using DELAY or TIME parameters to delay their execution.The file is modified in the same manner as for the ARTSTRN and the ARTSTR1 servers, except the "s" (synchronous) character used to prefix the name of these servers should be replaced by the "a" (asynchronous) character.To use parallel asynchronous transactions, with a MAXACTIVE parameter strictly superior to one, the dedicated server is the ARTATRN. Please refer to the section describing the installation of the ARTSTRN server to install the atrn_server.
• The psc command shows that five new services are running, one is dedicated to the asynchronous transaction while each synchronous transaction (SA00 to SA03) is duplicated (ASYNC_SA00 to ASYNC_SA03) to allow them to run in an asynchronous mode.To use non-parallel asynchronous transactions, with a MAXACTIVE parameter exactly equal to one, the dedicated server is ARTATR1.Please refer to the section describing the reasons and the installation of the ARTSTR1 server to install the ARTSTR1 server.ART CICS Runtime supports two methods for implementing asynchronous CICS delayed transactions launched using EXEC CICS START TRANSID requests:
• On z/OS, there are some time-related CICS START API options can be used to start a transaction at a specified time or after a specified interval, such as AT, TIME, AFTER, and INTERVAL. ART CICS Runtime provides a server, ARTSRM, for implementing these options. For more information, refer to ARTSRM Configuration in Oracle Tuxedo Application Runtime for CICS Reference Guide.To activate this server, configure ARTSRM in the *SERVERS section in the UBBCONFIG file. You can configure a set of ARTSRM servers only if they are in the same group for each CICS region. Following is an example.Listing 4‑16 Example of Configuring ARTSRM in UBBCONFIG
Note: Although implementing asynchronous transactions with /Q is still supported, when the START TRANID/CANCEL command is invoked, the request is submitted to the TRANCTL_[SYSID] service advertised by ARTSRM firstly. If the call gets the TPNOENT fail code, then use /Q to redispatch the request.Asynchronous transactions are launched when ASYNC_QSPACE for EXEC START is set with option INTERVAL or PROTECT.
1. An Oracle Tuxedo /Q Queue Space named ASYNC_QSPACE
2.
3.
1. Before using the script, define and export in your UNIX ~./.profile file:
• The QMCONFIG variable QMCONFIG- containing the full directory path that stores the Tuxedo /Q Queue Space ASYNC_QSPACE.
• The KIX_QSPACE_IPCKEY variable - containing the IPC Key for the Queue Space.
2. Execute mkqmconfig.sh from the command line to create the Tuxedo /Q features.
1. Listing 4‑17 Simple Application Tuxedo Queue ubbconfig Example
2. Then, two servers, TMQUEUE and TMQFORWARD, must be added to the ubbconfig file in the *SERVERS section.Using the tmadmin psr and psc commands check that four new servers and two new services are running:These transactions use CICS programs containing EXEC CICS requests relative to CICS Temporary Storage Queues.The statements used are EXEC CICS WRITEQ TS … END-EXEC, EXEC CICS READQ TS … END-EXEC, EXEC CICS DELETEQ TS … END-EXEC.To manage TS Queues, activate the ARTTSQ CICS Runtime Tuxedo Server.
• To activate this server, add this server to the *SERVERS section of the Tuxedo ubbconfig file:Listing 4‑20 Activating the ARTTSQ in the ubbconfig FileIs the Tuxedo Group Name to which ARTTSQ belongs.Use the Tuxedo tmadmin psr and psc commands to check that the server is running and that six new services are published:Listing 4‑21 Checking ARTTSQ Server and Services are RunningTS Queues are stored in a sequential file in a dedicated directory defined in the KIX_TS_DIR UNIX environment variable. This variable is defined and then exported from the ~/.profile UNIX System File:Modify the Tuxedo ubbconfig file to activate the new ARTTSQ server dedicated to their management.To use recoverable TS Queues you need to define an Oracle Table to contain the TS Queues. CICS Runtime provides a UNIX script to create all these tables: crtstable_Oracle.
1. Before using the script define and export from your UNIX ~./.profile file
• The ORA_USER variable containing the user ID used to connect to Oracle.
• The ORA_PASSWD variable containing the associated password.
2. Once the variables have been set, execute the crtstable_Oracle script.
3. Parameters send to the Oracle_XA Manager.Listing 4‑23 Simple Application Check For Recoverable TS Queues
• Write data to a transient data queue (WRITEQ TD command).
• Read data from a transient data queue (READQ TD command).
• Delete an intrapartition transient data queue (DELETEQ TD command).If an automatically initiated task does not empty the queue, access to the queue is not inhibited. The task may be normally or abnormally ended before the queue is emptied (that is, before a QZERO condition occurs in response to a READQ TD command). If the contents of the queue are to be sent to a terminal, and the previous task completed normally, the fact that QZERO has not been reached means that trigger processing has not been reset and the same task is reinitiated. A subsequent WRITEQ TD command does not trigger a new task if trigger processing has not been reset.
Table 4‑5 Source to Target Mapping CICS Runtime Resource DeclarationEvery CICS-like resource in CICS Runtime, is declared using a dedicated configuration file stored in directory ${KIXCONFIG}.Intrapartition queues are declared in the file tdqintra.desc, described in Oracle Tuxedo Application Runtime for CICS Reference Guide.In the current release are documentary only in tdqintra.desc, it is their value in /Q configuration which is taken in account.For detailed and accurate information on qmadmin and /Q configuration Using the ATMI /Q Component in the Tuxedo documentation.The script mk_td_qm_config.sh distributed with CICS Runtime provides an example of qspace creation and then of queue creation and configuration into /Q, to be used for TD intrapartition queues.
• KIX_TD_QSPACE_DEVICE: must contain the filename of the physical file containing the /Q database for TD queues.
• KIX_TD_QSPACE_NAME: contains the name of the logical QSPACE to create, which will contains the queues.
• KIX_TD_QSPACE_IPCKEY: a specific key which must be unique on the machine for the IPC used by the instance of /Q.The creation of the device (KIX_TD_QSPACE_DEVICE) and of the QSPACE are very standard, we will not detail them.A qopen QspaceName command, to open the qspace which will contain the queues must be made before the creation of any queue. The QspaceName must match the QSPACENAME in the resource declaration of these queue(s).Below is an example of an interactive queue creation using qmadmin, where the questions asked by qmadmin are in normal font, while the entries typed in by the user are in bold.Listing 4‑24 qopen Dialogqopen TD_QSPACEQueue name: TESTQueue capacity command: "TDI_TRIGGER -t S049"Listing 4‑25 qopen ScriptThis is the command to be launched when the trigger level is reached, in CICS Runtime it should be set to: TDI_TRIGGER -t TRID. Where TRID is the Transaction identifier of the transaction to trigger which should match the TRANSID of the resource configuration.Listing 4‑26 Activating the ARTTDQ in the ubbconfig FileThese transactions use CICS programs containing EXEC CICS requests relative to CICS Temporary Storage Queues.The statements used are EXEC CICS WRITEQ TS ... END-EXEC, EXEC CICS READQ TS ... END-EXEC, EXEC CICS DELETEQ TS ... END-EXEC.If at least one of your programs contains one of these statements and the queue is defined with POOLNAME (tsqmodel.desc), install and activate the new features of CICS Runtime without changing your other settings.CICS Runtime provides a UNIX script, crtsptable_{Oracle|UDB}, to create all these tables. Set MT_DB_LOGIN environment variable and then execute crtsptable_{Oracle|UDB} to create these tables. Set MT_DB_LOGIN to enter database connection information. For example: DBUSER/DBPASSWD@DBSID. See for Listing 4‑27 an example for Oracle database users.
2. Second, modify the Tuxedo UBBCONFIG file to modify the server group used by ARTTSQP to establish the connection to Oracle in the UBBCONFIG *GROUPS section.
3. Next, activate the ARTTSQP CICS Runtime Tuxedo server. To activate this server, add it to the UBBCONFIG *SERVERS section. See Listing 4‑28 for an example.
4. Last, use the Tuxedo tmadmin psr and psc commands to check that the server is running and that new services are published. See Listing 4‑29 for an example.When using ARTTSQP_UDB, you may need to do the followings to rebind the server for new DB2 server/tables.
1. Set environment variable MT_DB_LOGIN to enter database connection information.
2. Go to $KIXDIR/bin.
3. Listing 4‑27 Example of the UBBCONFIG Configuration Concerning the Server Group GRP02 Used by ARTTSQP ServerIs the Tuxedo UBBCONFIG keyword indicating definitions of server groups.Is the parameters sent to the Oracle_XA Manager.Listing 4‑28 Activating the ARTTSQP in the UBBCONFIG FileIs the Tuxedo UBBCONFIG keyword indicating a server section definition.Is the Tuxedo group name to which ARTTSQP belongs.Listing 4‑29 Checking ARTTSQP Server and ServicesFor several reasons, on z/OS, the Distributed Program Link function enables a local CICS program (the client program) to call another CICS program (the server program) in a remote CICS region via EXEC CICS LINK statements. CICS Runtime supports this feature used in multi-CICS architecture like MRO among migrated regions.
1. Listing 4‑30 Checking for Remote ProgramsEXECUtionset ==> Dplsubset Fullapi ! DplsubsetDYNAMIC(YES|NO)Remote server program name. An empty field is not relevant with DYNAMIC(YES) because the default is the client program name (PROGram ==>).Remote mirror transaction. An empty field is not relevant with DYNAMIC(YES) because the default is the mirror system transaction CSMI.
2. Then check in the programs, inside the EXEC CICS LINK API:Listing 4‑31 CICS LINK API For DPLIf at least one of your programs use the DPL, install and activate the ARTDPL server without changing your other settings.To activate this server, modify your ubbconfig file to add this server to the *SERVERS section of the Tuxedo ubbconfig file. This server belongs to the same Server Group as the Transactions Servers (ARTSTRN, ARTSTR1, ARTATRN, ARTATR1).Is the Tuxedo Group Name to which ARTDPL belongs.Use the Tuxedo tmadmin psr and psc commands to check that this server is running and that no new service is published:Listing 4‑33 tmadmin Commands to Check ARTDPL ServerTo allow an application to use distributed programs called in EXEC CICS LINK statements, these programs must be declared to CICS Runtime.
• In the programs.desc file, set REMOTESYSTEM (the 7th field of the csv format dataset), to remote SYSID name (KIXD in sample of Listing 4‑32).The default is local (empty field), meaning that local programs are declared because they can use the FULL CICS API.In our Simple Application example, if we suppose that RSSAT000, RSSAT001 are remote and RSSAT002 and RSSAT003 are local, then the programs.desc file is set to:
3. Using the Tuxedo tmadmin psr and psc commands, check that new services for DPL programs are published and managed by ARTDPL: KIXD_RSSAT0001 and KIXD_RSSAT0003.
Note: To avoid problems with homonyms, these distributed services have their names composed of the Tuxedo DOMAINID defined in the ubbconfig and the name of the program they manage.Listing 4‑35 Using tmadmin Commands to Check DPL ServicesTo reduce the scope of the services listed to only those managed by ARTDPL (SRVID=500), use the Tuxedo psc command followed with the -i srvid parameter to restrict the display to a particular server id.This area is addressed thru a pointer delivered by the CICS statement EXEC CICS ADDRESS CWA. If you find this CICS statement in your application, you have to implement this feature in CICS Runtime.Listing 4‑37 COBOL Example of CWA Usage
2. Modify your ~/.profile UNIX system file to export a new CICS Runtime variable, KIX_CWA_SIZE, and set it to the value found in the WRKAREA of the DFHSIT. If this variable is not declared, note that the default value is 0 and the authorized interval from 0 to 32760 bytes.
3. Modify your ~/.profile UNIX system file to export a new CICS Runtime variable, KIX_CWA_IPCKEY, and valorize it to a Unix IPC key to define the cross memory segment used as CWA.On z/OS, the TWA is a common storage area defined in memory for a CICS region that programs can use to save and exchange data between themselves during the execution time of one CICS transaction. In other words, this TWA can only be accessed by the programs participating in the transaction. This area is addressed thru a pointer delivered by the CICS statement EXEC CICS ADDRESS TWA. If you find an EXEC CICS ADDRESS TWA statement in your application, you have to implement this feature in CICS Runtime.Listing 4‑38 A COBOL Example of Use of the TWAAfter the CICS ADDRESS TWA, the address of the COBOL group named TRANSACTION-WORK-AREA is set to the address of the TWA allocated by CICS, meaning that TRANSACTION -WORK-AREA maps and refines this memory area. The total amount of this shared memory is defined for each transaction in the z/OS CSD configuration file in the field TWasize.The next screen shows the result of a z/OS CEDA system transaction where the TWasize parameter is set to 122 for the SA00 transaction code:Figure 4‑3 z/OS ceda System Transaction Example
1. Modify the CICS Runtime transactions.desc file to report the needed amount of TWA memory (TWasize>0).
2. For each transaction using programs with CICS ADDRESS TWA statements, modify the transactions.desc file to declare its TWasize in the sixteenth field of this csv format file.
Listing 4‑39 Configuration of TWA in the transactions.desc FileListing 4‑40 stderr_strn TWA Example
1. Modify the CICS Runtime transactions.desc file to configure TWASize needed for ARTDPL transaction.DFHMIRS is the internal mirror program in CICS that handles inbound function shipping. In CICS RT, this mirror program should be defined under the transaction used to run the linked program in the transaction resource file if TWA is used. In the list, ARTDPL runs remote linked program under transaction named CPMI and it has TWA size equal to 100.
Note: Listing 4‑42 stdout_dpl TWA ExampleThe ART CICS Transaction Trigger Monitor (ARTCKTI) behaves the same as the CICS CKTI transaction. It listens on one or multiple WebSphere MQ initiation queues, retrieves trigger messages when a trigger event occurs, and then forwards the trigger messages to the target transaction.ARTCKTI is a standalone Oracle Tuxedo server. The ARTCKTI server behaves as follows:One server instance can only monitor WebSphere MQ initiation queues within the same WebSphere MQ queue manager. The queues in different WebSphere MQ queue managers should be monitored by separate ARTCKTI server instances.
2. When trigger message has arrived, the ARTCKTI server retrieves the message.
4. Since MQTMC has many fields, it is always too complicated to send the structure as the parameter of EXEC CICS START call. MQTMC2 is used in CKTI to pass the structure as data to the START request for the trigger monitor.Since CICS CKTI transaction starts the target transaction with asynchronized call (EXEC CICS START), the ARTCKTI server also starts the target transaction with asynchronized call (Tuxedo tpacall).
6. User transaction retrieves the trigger message by CICS RETRIEVE, and performs operations on the WebSphere MQ application queue.Figure 4‑4 illustrates the behavior.Figure 4‑4 WebSphere MQ Trigger Condition
Note: By default, ARTCKTI is built with client mode and a specific Websphere MQ version. You need to rebuild ARTCKTI server if your ARTCKTI accesses Websphere MQ with server mode or if your Websphere MQ runtime version is lower than the version upon which the default ARTCKTI is built. For more information, see Rebuild ARTCKTI Server.ARTCKTI accepts the following parameters for the ubbconfig file.
• -i trigger_interval: specifies the maximum time (in milliseconds) that the ARTCKTI server waits for a message to arrive at the WebSphere MQ initiation queue.
• -s retry_interval: specifies the retry interval for ARTCKTI to reconnect to WebSphere MQ queue manager or reopen WebSphere MQ initiation queue upon failure.
• -m queue_manager_name: specifies the name of the WebSphere MQ queue manager to be monitored.
• -q queue1,queue2,……: specifies the name of the WebSphere MQ initiation queue to be monitored.WebSphere MQ can trigger CICS transactions when one or more messages are placed on the queue. ART for CICS provides ARTCKTI server as trigger monitor (equivalent to CICS CKTI transaction).To enable MQ Manager to trigger an ART for CICS transaction, the triggering queue and process need to be defined appropriately in the MQ Manager configuration. Listing 4‑43 shows a sample configuration.In the example above, INIT1 is defined as a trigger queue associated with process APP1.P, and specifies that the FIRST message placed on the queue will be used for triggering. The process definition that follows defines APPLTYPE as UNIX and specifies ART for CICS transaction ID to be triggered as APPLICID.Based on this definition, when the first message is queued on INIT1 queue, ARTCKTI trigger monitor will START TRANID('SA01') in ARTATRN server. The application transaction will usually drain the queue and process all available messages. The next time a new message is queued on INIT1, it will be triggered again.Prepare WebSphere MQ RM definitions by adding the following in $TUXDIR/udataobj/RM file if using local WebSphere MQ server:
Note: ${MQMDIR} is the environment variable which indicates the installation path of MQM.Build TMS_MQM server and put it in a directory included in the PATH set in setenv (for example, $TUXDIR/bin and $KIXDIR/bin) with correct execute permissions.Build transaction server (ARTSTR*/ARTATR*/ARTDPL) and put them in $KIXDIR/bin directory or a local directory under $APPDIR (but then add it in the $PATH definition in setenv) with correct execute permissions. See an example for ARTATRN.
• -M means "multiple RM involved".
• -r flags specify RMs to link with. For example, -r Oracle_XA points to Oracle DB RM definition, and -r MQSeries_XA_RMI_COB points to MQ RM for COBOL programs.Build ARTCKTI server if MQ-initiated transaction support is required.In general, default ARTCKTI does not need to be rebuilt unless WebSphere MQ version is changed or you need to use it in MQ server mode. (Default version is for use with WebSphere MQ client.)To build the ARTCKTI server, execute the following command as the Oracle Tuxedo administrator with write permission for the $KIXDIR/bin directory:
Note: $MQMDIR is the path where WebSphere MQ has been installed.ARTCKTI server does not need to be configured in the TMS group.ARTSTR*/ARTATR*/ARTDPL should be configured in the TMS group, and TMS group should be configured as MQM group.For proper connection to WebSphere MQ, the sequence is MQCONN, MQOPEN, MQxxx (GET/PUT), MQCLOSE, and MQDISC. In mainframe CICS, MQCONN and MQDISC are often handled by CICS as resource management functions and applications only do MQOPEN/MQxxx/MQCLOSE.To support this in ART for CICS, we use ART for CICS pre-processor to convert MQOPEN/MQCLOSE calls to KIX_MQxxxx wrappers, which then handle MQCONN and MQDISC under the covers. This approach also enables ART for CICS to handle connection issues and re-connect if necessary. Check the pre-processor output to verify that KIX_MQxxx calls are there.In terms of the MQ wrapper, MQ wrapper can help CICS transaction to recycle or free the MQ connection if the CICS transaction does not do this itself. prepro-cics.pl introcues a switch MQ_wrapper to enable this MQ wrapper. For every application server (for example, ARTSTR*/ARTATR*/ARTDPL), CLOPT -m queue_manager_name is introduced to specify the target MQ Manager, because MQ wrapper can help to do the MQCONNECT before MQOPEN but MQCONNECT needs to know which MQ Manager that it should connect to. For more information, see MQ_wrapper and WebSphere MQ Queue Manager Name.When using local WebSphere MQ client for remote connection to z/OS based MQ Manager, the EBCDIC-to-ASCII conversion is not automatically enabled. It can be enabled by setting MQGMO-CONVERT flag in MQGET options as shown in example below.Listing 4‑45 Example for MQGMO-CONVERTCOMPUTE MQGMO-OPTIONS = MQGMO-WAITFor MQPUT the ASCII-to-EBCDIC conversion is done automatically if MQMD-FORMAT is set to MQFMT-STRING. For example,When using local WebSphere MQ server, with channel defined as SENDERs, transcoding can be done without program change by adding CONVERT (YES) on the channel definition.Oracle Tuxedo ART Workbench adapts COBOL programs to target environment, in part by changing some mainframe numeric data types (BINARY/COMP) to compatible data type COMP-5, which is the native equivalent. This is transparent in COBOL applications.However, on Linux, for Websphere MQ libraries this can cause an issue as they require the use of BINARY types in the parameters passed in MQ calls. Similar data type mapping is done by Pro*COBOL pre-processor.Therefore, change the WebSphere MQ interface definitions from COMP-5 back to BINARY before the final compile stage. See an example of the changed MQ interface definitions (BINARY data type).
• PA1/PA2 cannot be used in user application when this feature is enabled.ART for CICS provides a system transaction, whose program name is DFHALST, to get and show application list for a user when doing multiple session management. The transaction calls a user plug-in to get the list.You should provide this plug-in, and place the library in the correct library path so that DFHALIST can call it. For more information about this plug-in, see "CICS Runtime Integration with Application List Transaction" in Oracle Tuxedo Application Runtime for CICS Reference Guide.You should define application list transaction (ALST) in transactions.desc, and set the program to DFHALST. ARTSTRN servers will load this transaction.For more information, see "ALST (Application List Transaction)" in Oracle Tuxedo Application Runtime for CICS Reference Guide.You should configure GMTRAN=CESN in system.desc to let ART for CICS initiate CESN transaction automatically when a user connects to it.You should enable security to do multiple session management. For more information, see "Security Configuration" in Oracle Tuxedo Application Runtime for CICS Reference Guide.
• ARTTCPL, specifying its -t option. For more information, see "ARTTCPL/ARTTCPH Configuration" in Oracle Tuxedo Application Runtime for CICS Reference Guide.
• ARTCNX, specifying its SYSID.
• ARTSRM (to prevent the same user connects to ART for CICS via different terminals).
• ARTSTRN (to run application list transaction and user transactions).Listing 4‑47 Example of Configuring UBBCONFIG
• Move the cursor to the field at the left of the session that you want to activate, and press Enter. DFHALST actives the session and switches the display to the application screen.
• Type /sessid in the command field and press Enter.In user transaction, issue CICS RETURN without TRANSID parameter to end the transaction, and then ART for CICS terminates the session of the transaction.CICS Runtime server, ARTCSKL, is ART for CICS TCP/IP socket listener. When client request comes, it passes the request to work task for processing, and then waits for another client request. CICS Runtime transaction server, ARTATRN/ARTATR1, starts up and runs user-written transactions.You can use ART for CICS TCP/IP socket interface to write these transactions. The user-written transaction uses EXEC CICS RETRIEVE commands to make a socket available to ARTATRN/ARTATR1 (it should use the output parameter to call takesocket()), uses write/read() to transfer data, and then closes the socket.
• Client applications and user transactions running in ARTATRN/ARTATR1 can be written in both C and COBOL languages. The errno returned by C socket API on all supported platforms and the errno returned by COBOL socket API on AIX/Solaris platforms are different from mainframe; you should use macro definition in errno.h in your programs.
• Only supports to start user transactions using EXEC CICS START with no delay interval.
• ARTCSKL is the only supported socket listener; user-written listener is not supported.ART for CICS supports the above functions as well, providing a set of C APIs and extended COBOL APIs. Table 4‑7 lists the supported C APIs; the last three functions are provided by ART for CICS while other functions can use OS socket library directly. Table 4‑8 lists the supported extended COBOL APIs.
Table 4‑7 Supported C APIs A server issues the accept() call to accept a connection request from a client. The call uses a socket already created with a socket() call and marked by a listen() call. The bind() call binds a unique local port to an existing socket. Note that, on successful completion of a socket() call, the new socket descriptor does not have an associated port. A close() call shuts down a socket and frees all resources allocated to the socket. If the socket refers to an open TCP connection, the connection is closed. If a stream socket is closed when input data is queued, the TCP connection is reset rather than being cleanly closed. A connect() call attempts to establish a connection between a local socket and a remote socket. For a stream socket, the call performs two tasks. The fcntl() call controls whether a socket is in blocking or nonblocking mode. gethostid() gets the unique 32-bit identifier for the current host in network byte order. This value is the default home IP address. gethostname() returns the name of the host processor on which the program is running. getpeername() returns the name of the peer connected to a specified socket. A getsockname() call returns the current name for socket s in the sockaddr structure pointed to by the name parameter. getsockopt() gets options associated with a socket. The ioctl() call controls the operating characteristics of sockets. The listen() call indicates a readiness to accept client connection requests. The read() call reads data on a specified connected socket. The recv() call receives data on a specified socket. The recvfrom() call receives data on a specified socket. The recvfrom() call applies to any datagram socket, whether connected or unconnected. The select() call is useful in processes where multiple operations can occur, and it is necessary for the program to be able to wait on one or several of the operations to complete. send() sends data on an already-connected socket. sendto() sends data to the address specified in the call. setsockopt() sets the options. The shutdown() call shuts down all or part of a duplex connection. The socket() call creates an endpoint for communication and returns a socket descriptor representing the endpoint. write() writes data on a connected socket. A getclientid() call returns the identifier by which the calling application is known to the TCP/IP address space. The initapi() call connects your application to the TCP/IP interface. takesocket() acquires a socket from another program.
Note:
Table 4‑8 Supported Extended COBOL APIs A server issues the ACCEPT call to accept a connection request from a client. In a typical server program, the BIND call follows a SOCKET call and completes the process of creating a new socket. The CLOSE call shuts down a socket and frees all resources allocated to it. The CONNECT call is issued by a client to establish a connection between a local socket and a remote socket. The blocking mode of a socket can either be queried or set to nonblocking using the FNDELAY flag described in the FCNTL call. The LISTEN call:
• Completes the bind, if BIND has not already been called for the socket. The READ call reads the data on sockets. The SEND call sends data on a specified connected socket. SENDTO is similar to SEND, except that it includes the destination address parameter. The SHUTDOWN call can be used to close one-way traffic while completing data transfer in the other direction. The SOCKET call creates an endpoint for communication and returns a socket descriptor representing the endpoint. The WRITE call writes data on a connected socket. GETCLIENTID call returns the identifier by which the calling application is known to the TCP/IP address space in the calling program. The INITAPI calls connect an application to the TCP/IP interface. The TAKESOCKET call acquires a socket from another program and creates a new socket.
Note: Figure 4‑5 shows the sequence of CICS Runtime commands and socket calls involved in setup. CICS Runtime commands are prefixed by EXEC CICS; all other numbered items in this figure are ART for CICS TCP/IP calls.Figure 4‑5 The Client-Listener-Server Application Set
Table 4‑9 Client Call Sequence For CICS TCP/IP, the domain can only be the TCP/IP internet domain (AF_INET). The type can be stream sockets (SOCK_STREAM), or datagram sockets (SOCK_DGRAM). The protocol can be either TCP or UDP.If successful, the SOCKET call returns a socket descriptor, s, which is always a small integer. Notice that the socket obtained is not yet attached to any local or destination address. Client applications use this to establish a connection with a remote server. You must define the local socket s (obtained above) to be used in this connection and the address and port number of the remote socket. The system supplies the local address, so on successful return from CONNECT, the socket is completely defined, and is associated with a TCP connection (if stream) or UDP connection (if datagram). This sends the first message to ARTCSKL if it runs in standard mode. The listener in standard mode requires ARTCSKL input format from the client in its first transmission. The message contains the CICS transaction code as its first 4 bytes of data. You must also specify the buffer address and length of the data to be sent. The Listener server, ARTCSKL, is provided as part of ART for CICS TCP/IP. Figure 4‑5 shows the calls issued by ARTCSKL. Your client and server call sequences must be prepared to work with this sequence. For more information, see ART for CICS TCP/IP Listener (ARTCSKL).
This retrieves the data passed by the EXEC CICS START command in the Listener program. This data includes the socket descriptor and the Listener client ID as well as optional additional data from the client. The TAKESOCKET parameters must specify the socket descriptor to be acquired and the client ID of the Listener. This information was obtained by the EXEC CICS RETRIEVE command. ARTCSKL is the listener of ART for CICS TCP/IP socket and can perform the same functions as CICS TCP/IP listener CSKL. When client request comes, it passes the request to work task for processing, and then waits for another client request. ARTCSKL can run in standard or enhanced mode; you can set the mode through FORMAT parameter of ART for CICS TCP/IP socket listener configuration file (listener.desc).
Note: ARTCSKL is the only supported socket listener; user-written listener is not supported.As shown in this figure, client A has already established a connection with the server, which has created a user transaction run in ARTATRN/ARTATR1. This allows the server to process client B's request without waiting for client A's transaction to complete. More than one user transaction can be started in this way.ARTCSKL is written to make some of this activity go on in parallel, and it has a listening socket that has a port to receive incoming connection requests. When a connection request is received, ARTCSKL creates a new socket representing the endpoint of this connection and passes it to the applications by way of TCP/IP socket givesocket/takesocket calls.
•
• The listener in standard mode starts the user transaction based on information in the first message on the new connection. The format of this information is given in following ARTCSKL Input Format. For the listener in enhanced mode starts the user transaction based on information in ART for CICS TCP/IP socket listener configuration file (listener.desc).ARTCSKL in standard mode requires the following input format from the client in its first transmission. The client should then wait for a response before sending any subsequent transmissions. Input can be in uppercase or lowercase. The commas are required.ARTCSKL in enhanced mode does not need this input format; ART for CICS gets transaction information from its TCP/IP Socket Listener configuration file (listener.desc).kc (only KC in uppercase is supported)Optional. The startup type that for ART for CICS task control. Only KC in uppercase is supported, indicating that the user transaction is started using EXEC CICS START with no delay interval. If this field is left blank, startup is immediate using the task control (KC).hhmmss (not supported)There are two different formats for the listener output; one for user transaction started through a standard listener (see Listing 4‑48) and one for user transaction started through the enhanced listener (see Listing 4‑49).A user transaction program, using the EXEC CICS RETRIEVE function to get the data passed to it by the listener, should expand the storage it has allocated to contain the IPv6 socket address structure. The LENGTH specified on the EXEC CICS RETRIEVE function should reflect the amount of storage allocated to contain the listener output format. The LENGERR flag is raised if the LENGTH is smaller than the amount of data sent. Coding a HANDLE condition allows you to contain this.
Note: Output through ART for CICS Transient Data Queue (by ARTCSKL) is not supported.char listen_name[8]; /* Listener name */char listen_taskid[8]; /* Listener task id */char client_in_data[35]; /* Client-in-data */char ote[1]; /* Threadsafe ind. @W1C */char reserved2[68]; /* reserved */short client_in_data_length; /* Length of data recved */char client_in_data_2; /* data from Client */
• Declare resources on ART for CICS TCP/IP socket listener configuration file (listener.desc). For more information, see "TCP/IP Socket Listener Configuration File" (listener.desc) in Oracle Tuxedo Application Runtime for CICS Reference Guide.
• Configure CICS Runtime server ARTCSKL and ARTATRN/ARTATR1. CICS Runtime server ARTCSKL and ARTATRN/ARTATR1 should be configured on the same machine. For more information about ARTCSKL and ARTATRN/ARTATR1 servers, see Oracle Tuxedo Application Runtime for CICS Reference Guide.In z/OS, ISSUE PASS command is used to transfer CICS regions without terminal reconnection; users can also implement data transference using LOGONMSG. When ISSUE PASS is invoked, the GMTRAN of destination region will be invoked by force.It is required to set environment variable ISC_ENABLE to YES. For more information, please refer to ISC_ENABLE.system.desc defines system initialization parameters of CICS regions.Listing 4‑50 Example for system.desc ConfigurationsIn this example, two CICS regions are defined. SYSID are specified as kixr and kixl respectively. On one hand, kixl specifies GMTRAN=ISSS; when users log in DBDCkixL, transaction are invoked automatically. On the other hand, kixr doesn't specify GMTRAN; default CSGM is used. LGNMSG specified in kixl enables data transference function using ISSUE PASS in EXTRACT LOGONMSG. For more information about system.desc, please refer to System Configuration File.If GMTRAN (not other system transactions, such as CSGM, CESN, or CESF) is defined, transactions/programs should be configured in transactions.desc/programs.desc, and then loaded by ARTSTRN/ARTSTR1. For more information about transactions.desc/programs.desc, please refer to Transaction Configuration File and Programs Configuration File.This configuration file defines terminal available to ART CICS; it is mandatory for using static LUNAME to logon ART CICS. For more information about terminals.desc, please refer to Terminal Configuration File.Listing 4‑52 Example for terminals.desc Configurations
• TMQUEUE should be configured for each CICS region.
• ARTLOGN should be configured.
• At least one ARTCNX should be configured for each CICS region.
• DDR published by ARTCNX should be configured (an example is provided as below).Listing 4‑53 Example for DDR Configurations
Notes: DDR configuration in UBB is mandatory. DDR routes login request to ARTCNX in different CICS regions by FML field CX_APPLID.ART reserved FML FIELD ID from 8100 to 8191 for DDR.Set environment variable ISC_ENABLE=YES to transfer CICS regions.Use Tuxedo tmadmin psr and tmadmin psc to check whether ARTLOGN starts successfully. ARTCNX and TMQUEUE are included in each region.Listing 4‑54 Example for Environment Variable DeclarationAfter a successful boot up, users can connect to ART CICS, and then logon screen prompts out for users to specify the CICS region (APPLID) to logon.Figure 4‑6 Logon ScreenFigure 4‑7 Typical End-to-End User CaseIn this scenario, there are three ART CICS regions, KIXA, KIXB, and KIXC, among which KIXA and KIXB communicates with each other via APPC protocol, and KIXA and KIXC communicates with each other via LU61 protocol.As shown in Figure 4‑7, the conversations occur in these regions are:
•
•
Note: CRM1 is a connection from CICA to TMA LU.Following CICS regions are defined in the system.desc configuration file:
• KIXA: APPC/LU61 front end
• KIXB: APPC back end
• KIXC: LU61 back end
• CICA: APPC front / back endFollowing connections are defined in the connection.desc configuration file:
•
•
•
•
•
•
•
•
• Following programs are defined in the programs.desc configuration file:
• Two programs in KIXA:
• COVSATMC: APPC client with view32
• RVS61C: LU61 client
• One program in KIXB:
• COVSATMS: APPC server with view32
• One program in KIXC:
• RVS61S: LU61 serverFollowing transactions are defined in the transactions.desc configuration file:
• Three transactions in KIXA:
•
•
•
• One transaction in KIXB:
•
• One transaction in KIXC:
• Following are configured in the UBBCONFIG file:
•
•
•
• GWSNAX gateway for TMA integration (for CICA)
Note: Following are configured in the DMCONFIG file:
• Import the CICA_KVA5 service from external
• Export the KIXB_KVA5 service to externalOn z/OS, asynchronous processing refers to a START command that starts a transaction on a remote system. ART CICS Runtime supports implementing this feature using the START command with a SYSID option.Define your CICS regions in the system.desc configuration file. Following is an example that defines two regions, KIXR and KIXX, with respective application definitions, DBDCkixR and DBDCKIXX.Listing 4‑55 Example of Defining Regions in system.descIt is required to configure ARTSRM server. For more information, please refer to ARTSRM Configuration.Suppose you have defined two regions, KIXR and KIXX, as shown in Listing 4‑55. Following is a configuration example.Listing 4‑56 Example of Modifying UBBCONFIGDefine your CICS regions in system.desc configuration file. Following is an example that defines two regions, KIXR and KIXX, with respective application definitions, DBDCKIXR and DBDCKIXX.Listing 4‑57 Example of Defining Regions in system.desc
• Configure the ARTSTRN servers for each CICS regionSuppose you have defined two regions, KIXR and KIXX, as shown in Listing 4‑57. Following is a configuration example.Listing 4‑58 Example of Modifying UBBCONFIGIn this example, requests from KIXX region are routed to ARTSTRN in GRPKIXX, and all other requests are routed to ARTSTRN in GRPKIXR.On z/OS, CICS programs can submit JCL/KSH job by the WRITEQ TD command and pass the JCL/KSH job statements to JES internal reader by TDQ. ART CICS Runtime supports this function by using the special TDQ definition and the internal service advertised by TuxJES system.Before using this feature, make sure ART Batch Runtime and TuxJES environment is set up. For more information, refer to Using Tuxedo Job Enqueueing Service (TuxJES).The submitted JCL/KSH job statements are transferred to TuxJES by the ARTTDQ server. To activate this server, configure ARTTDQ in the *SERVERS section in the UBBCONFIG file. Following is an example.Listing 4‑59 Example of Configuring ARTTDQ in UBBCONFIGTo implement the submitting JCL/KSH function, you need to specify the following fields in the tdqextra.desc configuration file:
• BLOCKFORMAT: An unblocked or blocked record format for the extrapartition queues that are used as the interface to the TuxJES internal reader.
• INTRDR: Set the TDQ definition as the internal reader.Indicates the block format is UNBLOCKED.
• For JCL job file: To submit a JCL job to TuxJES, one JCL end flag "/*EOF" needs to be written to TDQ INTRDR. If BLOCKFORMAT=B in tdqextra.desc is set for TDQ, two end flags "/*EOF" need to be written to TDQ.
• For KSH job file: To submit a KSH job to TuxJES, one KSH end flag "#EOF" needs to be written to TDQ.For more information, refer to TD Queue Extra Partition Configuration File in Oracle Tuxedo Application Runtime for CICS Reference Guide.On z/OS, CICS programs can submit JCL/KSH job by SPOOLWRITE command and pass the JCL/KSH job statements to JES internal reader by SPOOL. ART for CICS supports this function by using the internal service advertised by TuxJES system.Before using this feature, make sure ART Batch Runtime and TuxJES environment is set up. For more information, refer to Using Tuxedo Job Enqueueing Service (TuxJES).
Note: You should write end flag to SPOOL file to submit JCL/KSH job; otherwise, the job file written to SPOOL will be submitted automatically to TuxJES as a JCL job file when EXEC CICS SPOOLCLOSE is used.
• For JCL job file: To submit a JCL job to TuxJES, one JCL end flag "/*EOF" needs to be written to SPOOL file.
• For KSH job file: To submit a KSH job to TuxJES, one KSH end flag "#EOF" needs to be written to SPOOL file.For more information, see KIX_SPOOL_JOB_AUTO_SUBMIT and KIX_SPOOL_OUTPUT_DIR in Oracle Tuxedo Application Runtime for CICS Reference Guide.ART for CICS provides artcicsutil utility to track and dominate the CICS related resources from ART for Batch. It's always triggered by ART for Batch jobs. With the single command, ART for Batch jobs can open/close files, enable/disable CICS transactions, initiate CICS transactions, and etc.artcicsutil provides two modes of commend set to control ART for CICS. They are end-to-end mode (IPCP commend set and CAFC commend set) and interactive mode (interactive commend set). For all supported subcommands for each commend set, see artcicsutil in Oracle Tuxedo Application Runtime for CICS Reference Guide.
•
• artcicsutil must work together with the ART for CICS server ARTSRM. artcicsutil is the trigger to centralize the CICS resources related operations; ARTSRM is the portal of each CICS region in ART for CICS, and ARTSRM takes charge of all operation executions.
• Listing 4‑60 Sample JCL Containing IPCP Subcommands//IPCP01 EXEC PGM=IPCPBTCH,PARM='CICS CC ONLY=CICS3'In this JCL, IPCP program IPCPBTCH is issued inside (EXEC PGM=IPCPBTCH), the target CICS region is set as CICS3 (EXEC PARM='CICS CC ONLY=CICS3'), and CICS transaction HEL1 is started in the target CICS region (INIT KC HEL1). In this case, the IPCP subcommands can be issued by both EXEC PARM and JCL SYSIN DD.Listing 4‑61 KSH Converted by ART for WorkbenchIn this KSH (note artcicsutil -t IPCPBTCH "CICS CC ONLY=CICS3" subcommand), the program IPCPBTCH is translated to artcicsutil, EXEC PARM is passed to artcicsutil as its positional parameter, and all other subcommands (included in SYSIN DD) are stored by ART for Batch as a local file that artcicsutil can directly access. -t option is used to specify the type of command set; its value is set to IPCPBTCH (IPCP command set).In UBBCONFIG, set the following servers.
• ARTSRM (mandatory)ARTSRM is the proxy of artcicsutil utility and thus must be configured in the UBBCONFIG. The corresponding System Configuration File (system.desc) should be configured as well; see Configuring Resource Files for more information.ARTSRM must be configured in every ART for CICS region.
• ARTATRN (optional)If command INIT KC or ENAB/DISA KC in IPCP commend set or STRT in CAFC commend set is used in your JCL file, you should set ARTATRN in UBBCONFIG. You should also define the target transaction in the transaction configuration file (transactions.desc) and programs configuration file (programs.desc); see Configuring Resource Files for more information.See Listing 4‑62 for an example. ARTSRM server is mandatory, because all requests that artcicsutil issues are received by ARTSRM at first, and then ARTSRM acts as the proxy to ask the target CICS server to handle these requests. ARTATRN server is also specified because INIT KC subcommand is used in JCL (see Listing 4‑60); the target CICS transaction of INIT KC subcommand is the one that is just deployed at ARTATRN server.
• System Configuration File (system.desc)This is mandatory. See Listing 4‑63 for an example. CICS Runtime region CICS3 is configured, for this CICS3 is specified in your JCL file (see EXEC PGM=IPCPBTCH,PARM='CICS CC ONLY=CICS3' subcommand in Listing 4‑60).
• They are optional. If command INIT KC in IPCP commend set or STRT in CAFC commend set is used in your JCL file, ARTATRN is required; you should define the target transaction in transaction configuration file (transactions.desc) and programs configuration file (programs.desc).
• VSAM Configuration File (desc.vsam)This is optional. If command OPEN/CLOS DB in IPCP commend set is used in your JCL file, you should configure this VSAM configuration file (desc.vsam).Listing 4‑63 Example of Configuring System Configuration FileFor end-to-end mode, you should configure DMCONFIG. The key service entry, $(APPLID)_CICS_CTRL, should be exported/imported crossing ART for CICS domain (Listing 4‑64, note the CICS3_CICS_CTRL in bold) and ART for Batch domain (Listing 4‑65, note the CICS3_CICS_CTRL in bold). This service is advertised by each configured ARTSRM (ARTSRM is configured in every ART for CICS region); the prefix CICS3 is the APPLID of target CICS region.Note that the ${APPLID} here should be in uppercase.CICS3_CICS_CTRL RACCESSPOINT=BATCH1This use case describes the way to invoke artcicsutil utility in interactive mode. In this example, transaction EQDQ is started.
• Printing with a START command
1. Configure the printer terminal definition in typeterms.desc. Following is an example:
Note: ART CICS does not support the alternate size for printer, so the following attributes must not be defined in typeterms.desc for IBM-3287-1: scrnsize=alternate, altscreenrow, and altscreencolumn.
3. Configure the printer program definition to the ARTSTR1 program group in transactions.desc.
4.
5.
6. Configure the printer program group to the ARTSTR1 program group using CLOPT -l option in UBBCONFIG.
• If you use a PCOM client as the printer terminal, configure a LUNAME in the Telnet3270 interface and set the Session Type to Printer in the Session Parameters interface, as shown in following figures:Figure 4‑8 Configure a LUNAMEFigure 4‑9 Setting the PCOM Session TypeFigure 4‑10 Printing with a START CommandFigure 4‑10 shows a typical user case. The procedure to implement printing with a START command in such scenario are as follows:
2. Establish the connection from the Printer terminal to ART TCP with the LUNAME you specified previously.
4. Transaction A invokes an asynchronous transaction B with the START command, and specifies the TERMID as one of the LUNAME defined previously.
1.
2. Define PRT2 in terminals.desc.
3. After ART CICS is started, establish the connection between PCOMM (printer with the specified LUNAME= CICSPRT2) and ART CICS.When the ATI trigger level is reached, TDI_TRIGGER client will be invoked, and the -q and -d options will notify ART CICS to start a transaction associated queue_name and space_name on the terminal PRT2.ART CICS provides support for invoking web services from CICS applications using the INVOKE WEBSERVICE command. To implement this feature, you need to perform the configuration tasks described in the following sections.Convert your WSDL file into the Oracle Tuxedo metadata repository input file (MIF) using the Oracle SALT command utility, wsdlcvt. Specify its -C option to generate COPYBOOK. For more information, see Configuring an Oracle SALT Application.Use cpy2record tool to generate RECORD definition from the COPYBOOK that the previous step generates, and export environment variable for RECORD. For more information, see Using a RECORD Typed Buffer.Build SALT configuration file (using Oracle Tuxedo SALT utility wsloadcf), and loads service information into an Oracle Tuxedo service metadata repository (using tmloadrepos). For more information, see Configuring an Oracle SALT Application.Add a service section in webservice.desc configuration file, specifying REQUEST and RESPONSE in webservice.desc. Listing 4‑69 shows an example.Listing 4‑69 Example of webservice.desc ConfigurationListing 4‑70 Example of Adding TMMETADATA and GWWS in UBBCONFIGIn Tuxedo SALT deployment file, configure REST outbound service for each HTTP endpoint you want to access. You should set "outputbuffer" (of "Service" element) to "CARRAY", and specify "enableCustomHTTPHeaders" and "enableHTTPRequestLine" properties to enable the support for WEB WRITE/READ HTTPHEADER, WEB EXTRACT HTTPMETHOD/QUERYSTRING/... and so on. Listing 4‑71 is an example.Also, you should define and load other required Tuxedo SALT configurations, such as WSDF and Metadata configuration. See SALT Deployment File Reference for more information.Listing 4‑71 Example for Defining REST Outbound Service in SALTAdd an entry in URIMAP configuration file urimaps.desc. For example:Configure ART transaction servers to run user program, and configure Tuxedo SALT TMMETADATA and GWWS in UBBCONFIG. For example:Listing 4‑72 Example for Modifying UBBCONFIGIn Tuxedo SALT deployment file, configure REST inbound service you want to expose to HTTP client. You should set the "inputbuffer" (of "Method" element) to "CARRAY", specify "enableCustomHTTPHeaders" and "enableHTTPRequestLine" properties to enable support for WEB WRITE/READ HTTPHEADER, WEB EXTRACT HTTPMETHOD /QUERYSTRING/... and so on. Listing 4‑73 is an example.Also, you should define and load other required Tuxedo SALT configurations, such as WSDF and Metadata configuration. See SALT Deployment File Reference for more information.Listing 4‑73 Example for Defining REST Inbound Service in SALTConfigure ARTDPL to run user web aware programs, and configure Tuxedo SALT TMMETADATA and GWWS in UBBCONFIG. For example:Listing 4‑74 Example for Modifying UBBCONFIG
Note: Only the following ART for CICS application servers support this feature: ARTSTR1/N, ARTATR1/N, ARTCTR1/N, ARTWTR1/N, ARTDPL and ARTDPL_XN.You need to create one and only one shared library called libkixcallback.so, and declare the following two callback functions in this shared library.We recommend you put this shared library under the directory where the CICS Runtime product is installed. (Environment variable $KIXDIR is used to declare this directory. Usually it is $KIXDIR/lib directory.) When you do it, do not remove this shared library from this directory when your Oracle Tuxedo Application Runtime for CICS is updating or migrating.Oracle Tuxedo Application Runtime for CICS provides you a user header file called artkixcallback.h (published in directory $KIXDIR/include) to help you develop your shared library. It defines the following enumeration inside the header file.Listing 4‑75 User Header File artkixcallback.hListing 4‑76 StructureInclude your customized C library in $LD_LIBRARY_PATH for Linux/Solaris (or $LIBPATH for AIX). This library will be loaded dynamically in the runtime.If you want to create a shared memory used when ARTDPL server starts up, you need to create a shared library named libkixcallback.so, which exports two callback functions, and place the extended shared library under $KIXDIR/lib/ directory. For more information, see Create Shared Library libkixcallback.so.When the ARTDPL server starts up, it searches this extended shared library under $KIXDIR/lib at first. If it cannot find it, it continues to search $LD_LIBRARY_PATH for Linux/Solaris (or $LIBPATH for AIX). After finding this shared library, the ARTDPL server loads it.At this server initiation, you can create your shared memory. If the function fails, it returns nonzero and then the ARTDPL server cannot start up; if the function succeeds, it returns zero and then the ARTDPL server starts up as usual.If you want to open some database tables on your Linux platform when an ARTDPL server starts up, you need to create a named libkixcallback.so shared library, which exports two callback functions, and make sure the pathname of this C shared library is included in $LD_LIBRARY_PATH environment variable. For more information, see Create Shared Library libkixcallback.so.When the ARTDPL server starts up, it searches this customized shared library under $KIXDIR/lib. If it cannot find it, it continues to search under $LD_LIBRARY_PATH. After finding this shared library, the ARTDPL server loads it.When the shared library is initiated, you can open your database tables. If the function fails, it returns nonzero and then the ARTDPL server cannot start up; if the function succeeds, it returns zero and then the ARTDPL server starts up as usual.
•
• KIX_RESSEC=A: performs resource-based authorization when you access a resource in a transaction. This applies to all transactions.
• KIX_RESSEC=Y: performs resource-based authorization when you access a resource in a transaction. This only applies to the transactions whose RESSEC=Y is specified in transactions.desc.
• If KIX_RESSEC=Y is set, in transactions.desc, configure RESSEC=Y for the transactions that you want to check resource-based authorization.For more information, see Transaction Configuration File in Oracle Tuxedo Application Runtime for CICS Reference Guide.ART for CICS has a default authorization function called CheckResourceAuth.gnt (under ART for CICS installation directory). To integrate with external ESM, you need to replace the default CheckResourceAuth.gnt with your customized function.The function interface is listed in Integration with the External Security Manager in Oracle Tuxedo Application Runtime for CICS Reference Guide.
• Enable Tuxedo Security in UBBCONFIG.Enable Tuxedo security. For example, configure XAUTHSVR in UBBCONFIG to enable LDAP based authentication and authorization.For more information, see XAUTHSVR(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.Listing 4‑77 Enable Tuxedo Security in UBBCONFIGFor more information, see COBOL Program Debugging and Error Processing in CICS Runtime in Oracle Tuxedo Application Runtime for CICS User Guide and "Debug Configuration File" in Oracle Tuxedo Application Runtime for CICS Reference Guide.If ART for CICS user A wants to debug COBOL Program1 and ART for CICS user B wants to debug COBOL Program2, the two users should do the followings.
1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.
2. Input anim command lines.
3. User A and B either start up their own ART for CICS application servers with the same Linux account which starts up the anim utility, or dynamically change the debug configuration resource file without restarting the ART for CICS servers.
Note: The Linux user account that starts up the ART for CICS server must be the same as the Linux user account that runs the anim command line. Only the ANIMSRVID which the anim utility specifies will be debugged.If one ART for CICS user wants to debug two different COBOL programs in one transaction (for example, if ART for CICS user wants to debug COBOL Program1 and COBOL Program2, and both programs are in the same transaction), do the followings.
1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.If one ART for CICS user wants to debug two different COBOL programs with START TRANSID command, do the followings.
1. Add COBOL debug information into kix_cobol_dbg.cfg configuration file.If one ART for CICS user wants to debug two different COBOL programs with LINK command, do the followings.
1. Add the following COBOL debug information into kix_cobol_dbg.cfg configuration file.This log is the standard Tuxedo User Log (ULOG) whose name is contained in the system variable ULOGPFX of the Tuxedo ubbconfig file.When declaring a service in the Tuxedo ubbconfig file, each server has CLOPT options defined including two files:
Table 4‑11 Message Files by Server
• The groups of resources installed depending on the -l list parameter of each CICS Runtime server.
•
• One group (SIMPAPP) is selected with the -l option
• Information on the successful loading of these resources (Warning: zero TSQMODEL loaded).See also dynamic administration of CICS resources information in the Oracle Tuxedo Application Runtime for CICS Reference Guide.To switch your transaction from enabled to disabled, you have to modify the seventh field of this csv file, to change the previous value from an implicit (" " space(s)) or an explicit ENABLED status to the explicit DISABLED status.To enable a program, you have only to do the opposite, changing the STATUS field from DISABLED to ENABLED or " " (at least one space).Listing 4‑80 Log Report Showing Program Status|RSSAT002 |SIMPAPP |COBOL |USER|DISABLED |Each CICS Runtime Tuxedo Server reads a list of groups to be selected and installed at start up, contained in its CLOPT options after the -l parameter. To remove or add group(s) from an application, you have only to remove or add theses groups from this list for each CICS Runtime Tuxedo server.Listing 4‑81 Example of Application in ARTSTRN ServerIf you want to remove groups, you remove them from the -l lists when they are present, leaving only one : character between the remaining groups.Listing 4‑83 Example of Removing group1 in ARTSTRN Server
• In a C application, every EXEC CICS command is treated as if it had NOHANDLE or RESP option specified.
• /**/ is used for single line comments. Do not put a comment in the middle of an EXEC CICS command.
•
• ART CICS provides two methods to access COMMAREA:
• Provide an extern global pointer __commptr declared by ART CICS pre-processor automatically. __commptr is system reserved; users cannot define it as other usages.
• Provide an extern global pointer __eibptr declared by ART CICS pre-processor automatically. __eibptr is system reserved; users cannot define it as other usage.
• The EIB declarations are enclosed in #ifndef and #endif lines, but are not included in all translated files. ART CICS publishes header file dfheiblk.h to contain the definition of all the fields in the EIB. Each translated file just needs to include this header file and all actions are completed by pre-processor automatically.
• BMS screen attributes definitions: C versions of the DFHBMSCA and DFHAID files are supplied by CICS, and may be included by the application programmer when using BMS.
•
• ART CICS provides iscics() declared in cics.h as well, but users only need to modify makefile to include the header file path.
• Keep EXEC CICS as a whole in one line.
• #pragma will be automatically translated to comments.
• C function exit() will be translated to return.
• Keep C function main(), its parameter list, and parenthesis in one line. For example,
• COMMAREA should be a pointer. ART CICS only supports specifying a struct by pointer, not value.
• Using ADDRESS EIB
• Using global pointer __eibptr which points to EIBThe address of COMMAREA is not passed as an argument to a C main function; however, users can use the following two methods to obtain the address of the COMMAREA:
• Using ADDRESS COMMAREA
• ART CICS provides prepro-cics-C.pl for CICS/COBOL APIs translation. For more information about prepro-cics-C.pl, please refer to prepro-cics-C.pl.Use cob to compile C source code as a callable shared object. Please note that dynamic library must have the same name as the C source file name in uppercase.