CICS_for_Digital_UNIX_______________________________ Release Information Order Number: AV-QJG8D-TE Revision/Update Information: This is a new document Operating System: Digital UNIX V4.0A Software Version: CICS for Digital UNIX V2.1B Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ June 1997 Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. While Digital believes the information included in this publication is correct as of the date of publication, it is subject to change without notice. Digital Equipment Corporation makes no representations that the interconnection of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. © Digital Equipment Corporation 1997 © IBM 1997 The following are trademarks of Digital Equipment Corporation: AXP, Alpha AXP, AlphaGeneration, AXP, DEC, DECnet, Digital, VAX DOCUMENT, and the DIGITAL logo. CICS is a registered trademark of International Business Machines. Micro Focus, Micro Focus COBOL, and Animator are registered trademarks of Micro Focus Limited. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd. OSF/1 is a registered trademark of the Open Systems Foundation. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents 1 Introduction 1.1 Documentation ................................ 1-1 1.2 cicstermu .................................... 1-1 1.3 EXEC CICS SIGNON/SIGNOFF ..................... 1-1 1.4 Support for C++ .............................. 1-2 1.5 Support for Year 2000 ........................ 1-2 1.6 Terminal Autoinstalls ........................ 1-2 1.7 Epi3270 Server ............................... 1-2 2 Restrictions and Problems 2.1 Installation.................................. 2-1 2.1.1 Restrictions.............................. 2-1 2.1.2 Problems.................................. 2-3 2.2 Management.................................... 2-5 2.2.1 Restrictions.............................. 2-5 2.2.2 Problems.................................. 2-8 2.3 Intercommunication............................ 2-10 2.3.1 Restrictions.............................. 2-10 2.3.2 Problems.................................. 2-10 2.4 Development................................... 2-12 2.4.1 Problems.................................. 2-12 2.5 Documentation ................................ 2-15 2.5.1 Problems.................................. 2-15 2.6 CICS Demonstration Application................ 2-16 2.6.1 Restrictions ............................. 2-16 iii 3 Using C++ to Write Applications 3.1 Translating, Compiling and Linking C++ Applications.................................. 3-1 3.1.1 Using cicstcl for a C++ Program .......... 3-1 3.1.2 Using cicstran for a C++ Program ......... 3-1 3.1.3 Building a Class Library.................. 3-2 3.1.4 Linking Standalone CICS Programs against CICS Libraries............................ 3-3 3.2 Running C++ Programs ......................... 3-3 3.3 Debugging C++ Programs ....................... 3-3 3.4 Restrictions.................................. 3-4 4 EXEC CICS SIGNON and SIGNOFF 4.1 SIGNON........................................ 4-1 4.1.1 Description............................... 4-1 4.1.2 Options................................... 4-2 4.1.3 Conditions................................ 4-2 4.2 SIGNOFF....................................... 4-4 4.2.1 Description............................... 4-4 4.2.2 Conditions................................ 4-4 5 Year 2000 5.1 FORMATTIME ................................... 5-1 5.1.1 Format ................................... 5-1 5.1.2 Description .............................. 5-2 5.1.3 Options .................................. 5-2 5.1.4 Conditions................................ 5-5 6 Terminal Autoinstalls 6.1 Terminal definitions ......................... 6-3 6.2 Region definitions............................ 6-3 7 Migrating CICS from a DCE Cell to an RPC-only Setup 7.1 Procedure .................................... 7-1 7.2 Configure an RPC-only Setup................... 7-1 7.2.1 On Hosts with Regions..................... 7-1 7.2.2 On Hosts with SFSs........................ 7-2 7.2.3 On Hosts with PPC Gateway Servers ........ 7-3 7.2.4 On Hosts with Clients .................... 7-3 iv 8 CICSSNACFG Tables 2-1 Oracle Optional Patches .................. 2-2 v 1 _________________________________________________________________ Introduction This document describes a number of features that are new or changed in CICS for Digital UNIX Version 2.1B in addition to known problems and restrictions. 1.1 Documentation The documentation CICS for Digital UNIX Version 2.1B is the same as for Version 2.1A, with the following exception: Installation and Configuration has been revised. Messages and Codes has been revised. 1.2 cicstermu The cicstermu executable is a new client. It is similar to cicsterm, but with two significant differences: o It is more efficient, because it uses streams instead of depending on curses. o It does not provide support for NLS. Therefore, if you run with a locale other than en_US.ISO8859-1, cicstermu is not an option. 1.3 EXEC CICS SIGNON/SIGNOFF Two new commands have been added to the programming interface. These enable user supplied transactions to explicitly sign on and sign off from a region. This is documented in Chapter 4 Introduction 1-1 Introduction 1.4 Support for C++ 1.4 Support for C++ Chapter 3 tells you how to set up your system so that it will run transactions written in C++. 1.5 Support for Year 2000 CICS for Digital UNIX Version 2.1B is Year 2000 compliant. For your transactions to be Year 2000 compliant, they must be updated to use the new options on FORMATTIME that support 4-digit years and are documented in Chapter 5. 1.6 Terminal Autoinstalls The auto install of terminals has been changed, in order to improve performance. This is documented in Chapter 6. 1.7 Epi3270 Server Support for the Epi3270 server currently shipping in CICS for Digital UNIX Version 2.1B will be withdrawn in the next release. New users should use the CICS Client for PC or should access the CICS for Digital UNIX region by way of a mainframe TOR instead of using the Epi3270 Server. 1-2 Introduction 2 _________________________________________________________________ Restrictions and Problems 2.1 Installation 2.1.1 Restrictions Digital UNIX patches required If you are running with Digital UNIX Version 4.0A, you must install the following patches: 164.00 119.00 162.00 183.00 42.00 186.00 These patches are contained in the BL5 patch kit. For more information about the problems that they fix, refer to the BL5 patch kit documentation. If you are running a version of Digital UNIX other than Version 4.0A, ensure that either the base kit contains the patches listed above, or that you have the relevant patches. DCE DCE Version 2.0A and ECO#1 must be installed. Oracle Version 7.3.2.3 If you are using Oracle, Version 7.3.2.3 is required with the appropriate patches installed. Restrictions and Problems 2-1 Restrictions and Problems 2.1 Installation Patch number 424307 is mandatory for Oracle Version 7.3.2.3 when it is running on Digital UNIX Version 4.0A. This patch requires that you have the Motif server manager installed. When using CICS for Digital UNIX Version 2.1B and Oracle Version 7.3.2.3, it is necessary to have the Oracle patch that fixes bug number 424031. This patch contains the object file xaolog.o. This must be applied before you build the xaswitch file. If this patch is not applied, the region will issue a U8030 error from an XA-PREPARE command and terminate. In addition, Digital recommends that you consider the patches listed in Table 2-1. Table_2-1_Oracle_Optional_Patches__________________________ 397524 Fixes a problem associated with consistency of reads 411720 Fixes a major crash that can occur as a result of an issue with code boundaries 420001 Fixes a problem associated with very slow start with _______the_Oracle_parallel_server__________________________ LU6.2 Version 3.0 ECO #7 ECO #7 or later of the LU6.2 Version 3.0 server is required for intercommunication with an SNA network. DEC SNA Domain Gateway Version 2.0 ECO #2 of the DEC SNA Domain Gateway Version 2.0 must be installed. EPI 3270 Server The EPI3270 Server requires the 3270 Application Services Version 1.2 ECO#1 software to be installed. Internationalization 2-2 Restrictions and Problems Restrictions and Problems 2.1 Installation The only supported setting for the LANG environment variable is en_US.ISO8859-1. DCE SIA CICS for Digital UNIX does not support Digital DCE SIA. You must ensure that it is not enabled within your DCE cell. Enhanced Security CICS for Digital UNIX does not support Digital UNIX enhanced security. For CICS to work correctly, the Digital UNIX C2 subset must not be installed on your system. If you have to remove the C2 subset, ensure that after you have done so the file /var/tcb/audit/base_events is not on your system. 2.1.2 Problems Full DCE installation The installation procedure does not verify the DCE password requested. As a result, subsequent CICS configuration commands run as part of the installation procedure fail. Ensure that you enter the correct DCE password, or run the CICS configuration commands after the installation is complete. Verifying your installation This product does not support fverify. In order to verify your installation please use setld -v, rather than fverify. COBOL language support The cicsmkcobol command fails if you have not created a soft link in $COBDIR/lang from en_US to en_US.ISO8859-1. Restrictions and Problems 2-3 Restrictions and Problems 2.1 Installation This is a result of the Micro Focus use of short names for the locale names as they are listed in the $COBDIR/lang directories. To avoid this problem, you must set a soft link from the short name to the full locale name in use. For example, set a soft link from en_US to en_US.ISO8859-1. cicsmkcobol If you have upgraded your system from Digital UNIX 3.2 or higher, and cicsmkcobol fails because functions have been defined multiples times, you have omitted to carry out the clean up procedure to remove obsolete files during the upgrade. Either rename /usr/lib/libpthreads.a or use the clean up procedures associated with the Digital UNIX upgrade. Oracle Version 7.3.2 and cicsmkcobol When building the cicsprCOBOL for Oracle Version 7.3.2. for either XA or non XA transactions, use the following command: cicsmkcobol -L $ORACLE_HOME/lib -lsqlnet -lncr -lsqlnet -lclient \ -lcommon -lgeneric -lsqlnet -lncr -lsqlnet -lncr - lsqlnet \ -lclient -lcommon -lgeneric -lepc -lnlsrtl3 -lc3v6 - lcore3 \ -lnlsrtl3 -lcore3 -lxti -lm -lnlsrtl3 \ $ORACLE_HOME/precomp/lib/cobsqlintf.o \ $ORACLE_HOME/lib/libsql.a \ $ORACLE_HOME/lib/osntab.o 2-4 Restrictions and Problems Restrictions and Problems 2.2 Management 2.2 Management 2.2.1 Restrictions cicsmkcobol cicsmkcobol must be run because this upgrade modifies the contents of cicsprCOBOL. Shared memory CICS for Digital UNIX uses shared memory segments. If you are using either a region requiring greater than 4 MB for its definitions or a large number of regions on a system you may need to increase the default shared memory parameters. For more information, please refer to the documentation. Server Bindings File In a configuration in which DCE Name and Security Services are not used, the server bindings file is used to associate SFS servers with their string bindings. Multiple Network Interfaces If a machine has multiple network interfaces, it can have more than one network hostname and address. It is important to understand how the server bindings file works in this situation. When the server starts up, it finds matching entries in the server bindings file and checks that the hostname in the binding is valid for the local machine. Because of a restriction in the way it does the checking, it only accepts one of the machine's network hostnames as valid and rejects any others with the message: ... Ignoring well-known endpoint "< ... string binding ... >" -- not my network address. Restrictions and Problems 2-5 Restrictions and Problems 2.2 Management It is not always obvious which of the network hostnames will be accepted by the server, so the simplest solution is to omit the hostname from the binding. This has the same effect as supplying the valid hostname. The following two examples would, in effect, be the same: /.:/cics/sfs/server1 ncacn_ip_tcp:[2768] /.:/cics/sfs/server1 ncacn_ip_tcp:myhost[2768] In both cases, the SFS server will take the protocol sequence (tcp) and port number (2768) and register a binding using these and all available network addresses. If the second network name of the machine is "myhost2", either of the above would result in the two bindings: ncacn_ip_tcp:myhost[2768] ncacn_ip_tcp:myhost2[2768] If a client has to connect to the server from the same machine, it does not matter which network interface is used. If it has to connect from a remote machine, the network used could be significant operationally. When CICS wants to connect to the server, it first tries to locate it using the standard RPC mechanism. For this to succeed from a remote machine, CICS_HOSTS must be defined to include the machine running the server. However, locating the server in this way does not give the user any control over which network interface is used. If you want to control the network used, you must ensure that CICS_HOSTS is not set (or does not include the server machine) so that CICS will use the bindings file. When the other clients (sfsadmin, tkadmin, cicssdt) connect to the server, they go straight to the bindings file. The string binding from the first matching entry will be used, so this should contain the name of the network interface you want the connection to be made over. TASKSHAREDPOOLBASE 2-6 Restrictions and Problems Restrictions and Problems 2.2 Management This value may need to be changed if your region uses very large amounts of shared memory. This problem would show as CICS failing to attach shared memory during region start up. Translating Encina error numbers Translating Encina error numbers requires that the NLSPATH is set to include /opt/encina/msg/%L/%N. In order for this to be recognized, the user must not be root. Setting up a CICS Configuration that Uses Only DCE Runtime Services A CICS configuration set up to require and use only the DCE Runtime Services must not include any systems configured to operate in a DCE cell. Any earlier DCE configuration must be removed using the dcesetup clobber option. To start and stop the rpc daemon in this configuration, use cicscp. See also Chapter 7 Migration from DCE-lite to full DCE If the region has been migrated from a DCE-lite to a full DCE configuration, make sure that the ENCINA_BINDING_FILE environment variable is not set. Handling of operator identifier for transaction routing on CICS for Digital UNIX is different from CICS ESA Version 3.1 When a transaction is routed to a CICS for Digital UNIX region, generate an operator identifier from that of the Function Management Header (FMH) identifier, or from the default UD stanza entry. Restrictions and Problems 2-7 Restrictions and Problems 2.2 Management Terminal installation fails if a terminal name is defined with one character Terminals must have names that contain more than one character. Installation of terminals that have names of only one character fails. 2.2.2 Problems Lock files If the system is shut down or crashes without CICS or the SFS being correctly terminated, lockfiles will be left in place. When an attempted SFS or CICS restart occurs, the restart will fail with an error message indicating that a lockfile(s) is in place. Remove the lockfile(s). Preventing your logical volumes from filling Do not allow the SFS to fill either its data volume or its log volume. To determine how full the data volume is, use the following command: sfsadmin query lvol volume_name -server SFS server Example $ sfsadmin query lvol sfs_Scics01 -s/.:/cics/sfs/cis01 To determine how full the log volume is, use the following commands: tkadmin query logvol -server -server SFS server tkadmin query lvol -server -server SFS server Example $ tkadmin query logvol log_Scics01 -s/.:/cics/sfs /cics01 $ tkadmin query lvol log_Scics01 -s/.:/cics/sfs/cics01 2-8 Restrictions and Problems Restrictions and Problems 2.2 Management If the log volume is becoming full, turn on archiving, using the MRAArchivingEnabled field of the CICS SSD stanza (see CICS for Open Systems Administration Reference for more information). To make your transactions resilient to the possibility of either of the logical volumes becoming full, specify a DeadlockTimeout greater than 0 in the TD stanza, or when writing to the SFS use the NOSUSPEND option. The NOSUSPEND option when used on the WRITEQ will return the NOSPACE condition after the first write failure. Tuning As a minimum, the following are recommended: In the RD stanza set SafetyLevel=none. Enable program caching Enable shared memory FLT if you are using an SFS server cicssfs gives unaligned access message when used with only the DCE RPC daemon If your configuration uses only the DCE RPC daemon, you may see an unaligned access warning when using the cicssfs command. This is only a warning, and does not affect the operation of your SFS server. If you want to prevent the warning from occurring, unset the ENCINA_BINDING_FILE environment variable when running the cicssfs command. Restrictions and Problems 2-9 Restrictions and Problems 2.3 Intercommunication 2.3 Intercommunication 2.3.1 Restrictions cicssnaconfig does not configure remote gateways cicssnacfg does not configure DEC SNA Domain Gateways or Peer Servers. If you attempt to configure either, error messages will be issued. Support for single sessions CICS for Digital UNIX does not support single session SNA. Short transaction identifiers and CRTE Transactions will fail if the following conditions all apply: o They have an identifier of fewer than four characters. o They require following data. o They are routed to a region by means of CRTE. Ensure that all transaction identifiers have four character. 2.3.2 Problems Function ship request fails with A27D abend If cicssnacfg has not been run, a function ship requests fails with an A270 abend instead of returning SYSIDERR to the transaction. NCP and DEC SNA Peer Server retry endlessly When a Peer Server with llc2 and token ring connects to the NCP, ensure that the maximum frame size defined for NCP does not exceed that for the Peer Server. 2-10 Restrictions and Problems Restrictions and Problems 2.3 Intercommunication The NCP parameter is RCVBUFC on the LINE macro (for type NTRI). The value coded should specify a frame size that is large enough to accommodate the maximum frame size indicated by "maximum data size" on the DEC SNA Peer Server llc2 sap link entity, taking into account headers. See the DEC SNA Peer Server IBM Resource Guide, Section 3.2, and the DEC SNA Peer Server Management Manual, Section 8.5. Restrictions and Problems 2-11 Restrictions and Problems 2.4 Development 2.4 Development 2.4.1 Problems Comparing COMP-3 data items with 0 The COBOL compiler aborts if you compare a COMP-3 data item with the constant zero (0). To work round this problem, create a temporary numberic data item and initialize it to 0. Byte swapping after C program LINK to a COBOL program The task identifier associated with INQUIRE TASK is incorrectly byte swapped after the following steps: 1. A C program LINKS to a COBOL program, which then returns to the C program. 2. The C program uses INQUIRE TASK LIST and then INQUIRE TASK. 3270 data streams for terminals are incorrect Character streams that CICS produces for terminals (including the EPI) may contain invalid field attribute types and values. Oracle Non XA If your region is configured to use Oracle, application servers may spin after running non XA transactions. To prevent this, set the following environment variable as shown before starting your region: # export EPC_DISABLED=TRUE Handling Oracle errors Applications that use EXEC SQL do not have Oracle errors returned to them. 2-12 Restrictions and Problems Restrictions and Problems 2.4 Development To ensure that Oracle errors are returned to your applications, make sure that either of the following is true: o The applications contain the following line, before any EXEC SQL statements: # define A_OSF o A_OSF is defined in the makefile. Threads standards CICS uses the POSIX 1003.4A threads interface. You are advised, therefore, to use this interface if you wish to use the ECI or EPI programming interfaces. Restrictions and Problems 2-13 Restrictions and Problems 2.4 Development Recursive EXEC XCTL from COBOL transactions cause an exception If a COBOL transaction recursively calls EXEC XCTL, the transaction terminates with a COBOL exception. To avoid this problem, ensure that transactions do not call EXEC XCTL recursively. ECI Samples The makefile for the ECI sample programs is broken. 2-14 Restrictions and Problems Restrictions and Problems 2.5 Documentation 2.5 Documentation 2.5.1 Problems Administration Guide, Section 3.2.1 Table 3-1, Levels of authenticated RPC protection, is no longer correct in relation to "connect" and "call". Both "connect" and "call" are now supported. Administration Guide, Section 3.2.1 In Table 3-6, Attributes used to set authenticated RPC protection for Terminal Definitions (GSD), column 3 should read as follows: If the PPC Gateway Server is running unauthenticated, then this must be set to the same value as the RuntimeProtection attribute of any region that uses this PPC Gateway Server. Administration Guide, Section 3.2.2 Paragraph 2 should read as follows: To change the ACLs and set them correctly, you must understand how CICS regions, SFSs, and PPC gateway servers use DCE principals and groups. Administration Guide, Section 3.3.2.5 After the Note, the following should be inserted: The RSL key of the transaction to be started is also checked. Refer to Section 3.4.6.5 for further information. Administration Guide, Section 3.3.2.5 The last sentence on the page should be deleted: Refer to Section 3.4.6.5 for further information. Restrictions and Problems 2-15 Restrictions and Problems 2.6 CICS Demonstration Application 2.6 CICS Demonstration Application 2.6.1 Restrictions RPC PC Client and Configurations Using Only DCE Runtime The RPC PC Client fails when used with only the DCE runtime services. Alternatives are either to use the CICS Client for Windows software or to use a configuration that uses a DCE cell. Remote Configuration when using only the DCE runtime services When using only the DCE runtime services for a configuration that is using more than one host, you must follow the steps below: if you do not, the DEMO will not run correctly when the BMS Client is started. 1. Set up your configuration as in the following example: ________________________________________________________ __________Host__Region___DbServer____DbTypeDbSourceFile_ ClientProghost2 CATCLNT CustomerPrhost1 CATSERV ProductProhost1 CATSERV ActivityPrhost1 CATSERV CustomerDbhost1 CATSERV /.:/cics sfs CatCustDb.sdt /sfs/host1 ProductDb host1 CATSERV /.:/cics sfs CatProdDb.sdt /sfs/host1 ActivityDbhost1 CATSERV /.:/cics sfs CatActvDb.sdt _________________________/sfs/host1_____________________ ________________________ Note ________________________ Do not choose Configure.ALL to use this configuration. ______________________________________________________ 2. From the configure menu, select Build. 3. From the configure menu, select Install. 2-16 Restrictions and Problems Restrictions and Problems 2.6 CICS Demonstration Application 4. From the configure menu, select Load Database. 5. For both regions, CATCLNT and CATSERV, edit the file "environment" in the regions directory, adding the following line to the bottom of the file: CICS_HOSTS="host1 host2" where host1 and host2 are the hostnames of your machines. 6. Start the demo by choosing Start from the configure menu. Configurations Using SFSs on Remote Systems The demonstration application fails if configurations are selected in which regions use databases on other systems. This applies only to the database regions. Configurations Using SFSs on Remote Systems The demonstration application fails if configurations are selected in which regions use databases on other systems. This applies only to the database regions. Database Regions The database regions that you specify from the Demonstration Configuration Tool must be on the same system as the tool. DCE The DCE configuration on your system must be running and must match the DCE configuration that you select from the Demonstration Configuration Tool. If it does not, an error message will result when you attempt to "install" the Configuration Demonstration Tool. SFS Restrictions and Problems 2-17 Restrictions and Problems 2.6 CICS Demonstration Application Before you attempt to use any configurations from the Demonstration, all required SFS servers must have been created with the correct DCE configuration. By default, regions need the system default SFS, for example, /.:/cics /sfs/hostname. For instructions on creating an SFS, refer to Installation and Configuration. Quantity Field The quantity field is displayed on various "activity" screens to show users how many items are available, and later, how many were ordered. You can use the the Demonstration Configuration Tool to make this field viewable or to hide it, as with any other field. If you hide this field, the user will have no method of updating the quantity required: as a result, placing an order will cause all items to be ordered (if the customers credit allows). It is recommended that the Quantity field is always displayed. Configuration Tool Log File The Demonstration Configuration Tool writes informational messages to /tmp/cfgdemo.log. This file is not deleted by the Tool, and it will therefore continue to grow. If you wish to delete the file, you can do so safely at any time, although you may wish to wait until the Configuration Tool has completed any unfinished activity. 2-18 Restrictions and Problems 3 _________________________________________________________________ Using C++ to Write Applications 3.1 Translating, Compiling and Linking C++ Applications A CICS C++ application program must have a suffix of ccs and can be processed using cicstcl or cicstran, like a C application program, but there the similarity ends. The intermediate source file of C++ program has a suffix of .C, and the executable a suffix of .cpp. The command syntax is shown in Section 3.1.1 and Section 3.1.2. 3.1.1 Using cicstcl for a C++ Program Specify the C++ language by using the new language parameter CPP: # cicstcl - l CPP fred This produces the executable fred.cpp. # cicstcl -l CPP fred.ccs The cicstcl options that are valid for C application can also be used for C++ applications. 3.1.2 Using cicstran for a C++ Program As with cicstcl, specify the C++ language parameter, CPP: # cicstran - l CPP fred.ccs This produces fred.C. Then invoke the Digital UNIX C++ compiler. # cxx -taso -shared -threads -I/opt/cics/include -L/opt /cics/lib \ -lcxx -lcxxstd -lexc -lots -lcicsrt \ /opt/cics/lib/cicsprCpp -o fred.cpp fred.C Using C++ to Write Applications 3-1 Using C++ to Write Applications 3.1 Translating, Compiling and Linking C++ Applications 3.1.3 Building a Class Library To build a library lebref.a from fred1.ccs and fred2.ccs: 1. Translate fred1 and fred2: # cicstran -l CPP fred1 # cicstran -l CPP fred2 2. Compile the files produced: # cxx -taso -c -I $CICS/include -o fred1.o fred1.C # cxx -taso -c -I $CICS/include -o fred2.o fred2.C 3. Link and archive: # ld -taso -shared -no_archive -o libfred.so fred1.o fred2.o \ /opt/cics/lib/cicsprCpp -L/opt/cics/lib -lcicsrt -lc To build a transaction that uses a class library that you have built, use the following procedure: 1. Translate the CICS application using the following command: # cicstran -l CPP Main.ccs 2. Compile the translated code and link it against your class library: # cxx -taso -shared -threads -I/opt/cics/include \ -lcxx -lcxxstd -lexc -lots \ -L/opt/cics/lib -lcicsrt \ -L/directory_containing_class_library -lclass_library \ /opt/cics/lib/cicsprCpp -o Main.cpp Main.C When you start the region that is to be used with this transaction, be sure to set the LD_LIBRARY_PATH environment variable so that it includes the class library's directory path. 3-2 Using C++ to Write Applications Using C++ to Write Applications 3.1 Translating, Compiling and Linking C++ Applications 3.1.4 Linking Standalone CICS Programs against CICS Libraries When you develop standalone applications such as ECI/EPI applications that do not use the CICS translator, it is important to surround any lines that inlcude CICS header files with the extra statements shown in the example below: this ensures that any symbols referenced in your program are resolved correctly and are found in the relevant libraries. For example, in an ECI program, the traditional include statement for the cics_eci library would look like the following: extern "C: { #include } If you do not include the extern wrapper, your program will contain unresolved symbols and may produce errors at link time, even though you may be linking in the correct library. 3.2 Running C++ Programs You run C++ applications in the same way as C applications: the normal CICS resource definitions apply, and you may cache your C++ programs. When setting the LD_LIBRARY_PATH environment variable for your CICS region, ensure that you include any object directories in the path: if you do not, some objects will not be properly initialized, or will not even be found. A clue to a bad LD_LIBRARY_PATH setting is that the user's C++ transaction abends with an abend code of APCT. 3.3 Debugging C++ Programs Facilities for debugging C++ applications are the same as for C applications. You can use the CEDF transaction provided that you use the -c option when using cicstcl or cicstran. Using C++ to Write Applications 3-3 Using C++ to Write Applications 3.4 Restrictions 3.4 Restrictions In addition to the restrictions imposed on CICS C programs, there are a number of restrictions and considerations when writing CICS applications in C++: o If catch (...) is used, exceptions that were not generated by the application must be rethrown, using throw() with no argument. o Do not use iostream objects in CICS programs. o Do not place CICS statements in header files as part of an inline function definition. o CICS statements in class templates must be translated before the inclusion of the template class definition in any program. o All memory allocated by the application must be freed after use. o Programs in the cache are initialized only once. 3-4 Using C++ to Write Applications 4 _________________________________________________________________ EXEC CICS SIGNON and SIGNOFF 4.1 SIGNON Sign on to a terminal. SIGNON USERID(data-value) [PASSWORD(data-value)] [NEWPASSWORD(data-value)] Condition: INVREQ, NOTAUTH, USERIDERR 4.1.1 Description SIGNON associates the security capabilities and operator characteristics of the specified user with the terminal. SIGNON signs on to the terminal or principal facility associated with the issuing transaction. There is no implied signoff with the SIGNON command. If you want to sign on a user at a terminal to which a user is already signed on (including CESN), you must first issue a SIGNOFF command. Note that there is no default value for the USERID option. PASSWORD is used as a parameter which means that if there is a dump it may become visible. You should therefore clear the field as soon as possible after using PASSWORD. _______________ Other resource managers _______________ When this command is executed, CICS immediately recognizes the signon and establishes the specified user's security and operating attributes for the terminal. The transaction (and any associated task- related user exits, function shipping, or distributed transaction processing) may have invoked other resource managers (RMs), for example DB2. It is EXEC CICS SIGNON and SIGNOFF 4-1 EXEC CICS SIGNON and SIGNOFF 4.1 SIGNON unpredictable whether other RMs recognize the signon before the transaction terminates. The new user attributes apply for all RMs invoked by subsequent transactions at the terminal. ______________________________________________________ 4.1.2 Options NEWPASSWORD(data-value) specifies an optional 8-byte field defining a new password. This option is only valid if PASSWORD is also specified. PASSWORD(data-value) specifies an 8-byte password required by the external security manager (ESM). ________________________ Note ________________________ When running rpc only and no password is being used, you should define this parameter as PASSWORD(""). ______________________________________________________ USERID(data-value) specifies the 8-byte signon USERID. 4.1.3 Conditions INVREQ occurs in the following situations: o The terminal is already signed on (RESP2=9). o No terminal is associated with this task (RESP2=10). o Signon was attempted using transaction routing without using the CRTE transaction (RESP2=15). o The CICS ESM interface is not initialized (RESP2=18). o Command not allowed for a distributed program link server program (RESP2=200). Default action: Terminates the task abnormally. 4-2 EXEC CICS SIGNON and SIGNOFF EXEC CICS SIGNON and SIGNOFF 4.1 SIGNON NOTAUTH occurs in the following situations: o A password is required (RESP2=1). o The supplied password is wrong (RESP2=2). o A new password is required (RESP2=3). o The GROUPID is not known to the ESM (RESP2=23). Default action: Terminates the task abnormally. USERIDERR occurs in the following situations: o The USERID is not known to the external security manager (RESP2=8). o The USERID is all blanks or nulls (RESP2=30). Default action: Terminates the task abnormally. EXEC CICS SIGNON and SIGNOFF 4-3 EXEC CICS SIGNON and SIGNOFF 4.2 SIGNOFF 4.2 SIGNOFF Sign off from a terminal. SIGNOFF Condition: INVREQ 4.2.1 Description SIGNOFF enables you to sign off from the terminal or principal facility that you previously signed on to. When signoff is complete, the terminal reverts to the security capabilities and operator characteristics associated with the default user for this CICS region. The national language reverts to the national language of the default user, if defined, or the national language associated with the definition of the terminal. _______________ Other resource managers _______________ When this command is executed, CICS immediately recognizes the signoff and establishes the default attributes for the terminal. The transaction (and any associated task-related user exits, function shipping, or distributed transaction processing) may have invoked other resource managers (RMs), for example DB2. It is unpredictable whether other RMs recognize the signoff before the transaction terminates. The default attributes apply for all RMs invoked by subsequent transactions at the terminal. ______________________________________________________ 4.2.2 Conditions INVREQ occurs in the following situations: o No user is currently signed on (RESP2=1). o There is no terminal with this task (RESP2=2). o Signoff is attempted using transaction routing without using the CRTE transaction (RESP2=4). 4-4 EXEC CICS SIGNON and SIGNOFF EXEC CICS SIGNON and SIGNOFF 4.2 SIGNOFF o Command not allowed for a distributed program link server program (RESP2=200). Default action: Terminates the task abnormally. EXEC CICS SIGNON and SIGNOFF 4-5 5 _________________________________________________________________ Year 2000 5.1 FORMATTIME Selects the format of date and time. 5.1.1 Format FORMATTIME ABSTIME(data-area) [DATE(data-area)] [DATEFORM(data-area)] [DATESEP[(data-value)]] [DAYCOUNT(data-area)] [DAYOFMONTH(data-area)] [DAYOFWEEK(data-area)] [DDMMYY(data-area)] [DDMMYYYY(data-area)] [MMDDYY(data-area)] [MMDDYYYY(data-area)] [MONTHOFYEAR(data-area)] [TIME(data-area) [TIMESEP[(data-value)]]] [YEAR(data-area)] [YYDDD(data-area)] [YYDDMM(data-area)] [YYMMDD(data-area)] [YYYYDDD(data-area)] [YYYYDDMM(data-area)] [YYYYMMDD(data-area)] Condition: ERROR Year 2000 5-1 Year 2000 5.1 FORMATTIME 5.1.2 Description FORMATTIME transforms the absolute date and/or time into any of a variety of formats. Normally, the ABSTIME argument is the value returned by an ASKTIME ABSTIME command. The following example shows the effect of some of the options of the FORMATTIME command: EXEC CICS ASKTIME ABSTIME(utime) EXEC CICS FORMATTIME ABSTIME(utime) DATESEP('-') DDMMYY(date) TIME(time) TIMESEP If utime has the value 002837962864828 in milliseconds on completion of the ASKTIME ABSTIME command, this gives the values 06-12-89 for date and 19:01:05 for time. To obtain an elapsed time in a particular format, the ABSTIME argument can be the difference between two values returned by ASKTIME, and options such as DAYCOUNT and TIME can be specified. 5.1.3 Options ABSTIME(data-area) specifies the time, in milliseconds since 0000 hours (local time) on 1 January 1900, that is to be converted to an alternative format. The format of the argument is: COBOL PIC S9(15) COMP-3 C or C++ char data-area[8]; If the ABSTIME argument is in an incorrect form, the ERROR condition occurs. 5-2 Year 2000 Year 2000 5.1 FORMATTIME DATE(data-area) specifies an eight-character field to receive the date in the format indicated by the DateForm attribute in the RD stanza (see Administration Guide). The separator (if any) used in the returned value is determined by the DATESEP option. You should normally use this option only if the date is needed for output purposes. Where a date is needed for analysis, you should request the date in explicit form, for example, using the MMDDYY option. DATEFORM(data-area) specifies a six-character field to receive the format of the installation-defined date. CICS returns YYMMDD, DDMMYY, or MMDDYY according to the DateForm attribute in the RD. DATESEP(data-value) specifies the character to be used as the separator between the year and the month, between the day and the month, and between the year and the day (according to the date format). If you omit this option, no separator is supplied. If you omit data-value, a slash (/) is assumed as the separator. DAYCOUNT(data-area) specifies a 32-bit binary field to receive the number of days since 1 January 1900 (day 0). This option is useful if you need to compare the current date with a previous date that has, for example, been stored in a file. DAYOFMONTH(data-area) specifies a 32-bit binary field to receive the number of the day in the month. DAYOFWEEK(data-area) specifies a 32-bit binary field to receive the relative day number of the week: Sunday=0, Saturday=6. You can convert this number, in your application program, to a textual form of day in any language. DDMMYY(data-area) specifies an eight-character field to receive the date in DDMMYY format, for example, 21/10/96. Year 2000 5-3 Year 2000 5.1 FORMATTIME DDMMYYYY(data-area) specifies a ten-character field to receive the date in DDMMYYYY format, for example, 21/10/1996. MMDDYY(data-area) specifies an eight-character field to receive the date in MMDDYY format, for example, 10/21/96. MMDDYYYY(data-area) specifies a ten-character field to receive the date in MMDDYYYY format, for example, 10/21/1996. MONTHOFYEAR(data-area) specifies a 32-bit binary field to receive the relative month number of the year: January=1, December=12. You can convert this number, in your application program, to the name of the month in any language. TIME(data-area) specifies an eight-character field to receive the current 24-hour clock time in the form hh:mm:ss, where the separator (shown here as :) is determined by the TIMESEP option. TIMESEP(data-value) specifies the character to be used as the separator in the returned time. If you omit this option, no separator is assumed and six bytes are returned in the eight-character TIME field. If you omit data-value, a colon (:) is used as the separator. YEAR(data-area) specifies a 32-bit binary field to receive the full four- digit number of the year, for example, 1990. YYDDD(data-area) specifies a six-character field to receive the date in YYDDD format, for example, 96/301. YYDDMM(data-area) specifies an eight-character field to receive the date in YYDDMM format, date, for example, 96/21/10. 5-4 Year 2000 Year 2000 5.1 FORMATTIME YYMMDD(data-area) specifies an eight-character field to receive the date in YYMMDD format, for example, 96/10/21. YYYYDDD(data-area) specifies an eight-character field to receive the date in YYYYDDD format, for example, 1996/200. YYYYDDMM(data-area) specifies a ten-character field to receive the date in YYYYDDMM format, for example, 1996/21/10. YYYYMMDD(data-area) specifies a ten-character field to receive the date in YYYYMMDD format, for example, 1996/10/21. 5.1.4 Conditions ERROR occurs if the ABSTIME argument is specified in an incorrect form. Default action: Terminates the task abnormally. Year 2000 5-5 6 _________________________________________________________________ Terminal Autoinstalls A number of changes have been made to the autoinstall code which increase the speed at which terminals can be connected to a region. One of these changes is the addition of a new algorithm to that generates terminal names. This algorithm produces a set of terminal names that are different from those produced by the algorithms used by default in previous CICS releases and which can can be more efficiently searched. You can select the way in which terminals will be installed for your region. There are three options: 1. default - NetNames are checked for uniqueness. - Terminals are not preinstalled before the terminal autoinstall user program is called. - New style names are generated. 2. old_style - NetNames are checked for uniqueness. - Terminals are preinstalled before the terminal autoinstall user program is called. - Old style names are generated. 3. no_netname_check - NetNames are NOT checked for uniqueness. - Terminals are NOT preinstalled before the terminal autoinstall user program is called. - New style names are generated. Terminal Autoinstalls 6-1 Terminal Autoinstalls The way in which terminals are installed is determined from one by the AutoinstallMode entry in the RD stanza, which may have any of the following values: default, old_style, no_netname_check. The changes made to support this have necessitated changes in the TD and RD stanzas, described in the following sections. 6-2 Terminal Autoinstalls Terminal Autoinstalls 6.1 Terminal definitions 6.1 Terminal definitions RecoverTerminal This attribute determines whether the terminal is recovered during a warm start after a region failure. The possible values are yes (the default) and no. If the value of this attribute is yes, the terminal will be reinstalled automatically during a warm start of a region after failure. If the value is no, the terminal will not be recovered. If a terminal is not recoverable, the time taken to install the terminal is slightly shorter and the time taken to warm start the region will also be shorter. 6.2 Region definitions AutoinstallMode The AutoinstallMode entry specifies the way in which terminals are installed from model definitions. There are three different values that this entry can have: default, old_style, no_netname_check. The old_style setting provides functionality similar to that in earlier releases of CICS on Digital UNIX. The default setting significantly improves performance, because the terminal names are generated using a different algorithm which can be searched more efficiently. Additionally, terminals are installed after the CHAT exit has been called, this means that if the exit modifies the given name, the terminal is only installed once. The no_netname_check setting provides the fastest method of installing terminals at the cost of there being no checks for uniqueness of netnames. This option should only be used if the CHAT terminal autoinstall user program can gurantee that the names are unique or if there are no connections being made from an SNA network. Terminal Autoinstalls 6-3 7 _________________________________________________________________ Migrating CICS from a DCE Cell to an RPC-only Setup These procedures describe how to migrate regions, clients, and Encina servers in a DCE cell to an RPC-only setup. 7.1 Procedure Before carrying out the migration, do the following: 1. Shut down all CICS regions and SFSs in such a way that they can be warm started. 2. If you are using a DCE client, use the following command to destroy the DCE configuration: dcesetup stop dcesetup clobber 3. Use the following command to destroy your DCE configuration: cicscp destroy dce 7.2 Configure an RPC-only Setup 7.2.1 On Hosts with Regions 1. Use the following command to configure the RPC-only process: cicscp -v -l logFile create dce -R 2. Change the Region Definitions (RD) AuthenticationService attribute to CICS, the NameService attribute to NONE, and the RuntimeProtection attribute to none in the permanent database. Use the following commands: cicsupdateclass -r regionName -w -c rd \ Migrating CICS from a DCE Cell to an RPC-only Setup 7-1 Migrating CICS from a DCE Cell to an RPC-only Setup 7.2 Configure an RPC-only Setup -a AuthenticationService -n CICS cicsupdateclass -r regionName -w -c rd \ -a NameService -n NONE cicsupdateclass -r regionName -w -c rd \ -a RuntimeProtection -n none 3. Set the CICSPassword attribute for all User Definitions (UD) that will use password checking. This password is encrypted when stored in the resource definition databases. In the following command example, udKey is the key for the UD entry that you are changing and passWord is the password you are adding to the entry. cicsupdateclass -r regionName -w -c ud \ -a CICSPassword -n passWord -k udKey 4. Do the procedure described in "Procedure: Set the $CICS_ HOSTS environment variable for the region". 7.2.2 On Hosts with SFSs 1. Use the following command to configure the RPC-only process: cicscp -v -l logFile create dce -R 2. Set the NameService attribute to NONE and the ProtectionLevel attribute to none for all Structured File Server Definitions (SSD) entries on that host as shown: cicsupdateclass -w -c ssd -a NameService -n NONE -k \ "/.;/cics/sfs/serverName" cicsupdateclass -w -c ssd -a ProtectionLevel -n none -k \ "/.;/cics/sfs/serverName" It is important that you use a semicolon (;), not a colon (:), when specifying the cell-relative name when using cicsupdateclass. 7-2 Migrating CICS from a DCE Cell to an RPC-only Setup Migrating CICS from a DCE Cell to an RPC-only Setup 7.2 Configure an RPC-only Setup 3. Do the procedure described in CICS on Open Systems Administration Guide, "Procedure: Set up a binding file for the SFS". 7.2.3 On Hosts with PPC Gateway Servers 1. Use the following command to configure the RPC-only process: cicscp -v -l logFile create dce -R 2. Set the NameService attribute to NONE and the ProtectionLevel attribute to none for all Gateway Server Definitions (GSD) entries on that host as shown: cicsupdateclass -w -c gsd -a NameService -n NONE -k \ "/.;/cics/gateway/gatewayName" cicsupdateclass -w -c gsd -a ProtectionLevel -n none -k \ "/.;/cics/gateway/gatewayName" It is important that you use a semicolon (;), not a colon (:), when specifying the cell-relative name when using cicsupdateclass. 3. Do the procedure described in "Setting up a string binding file in the PPC Gateway Server" in the Intercommunication Guide. 7.2.4 On Hosts with Clients 1. Run the following command: cicscp -v -l logFile create dce -R 2. Do the procedure described in CICS on Open Systems Administration Guide, "Procedure: Set the CICS_HOSTS environment variable on the clients". Migrating CICS from a DCE Cell to an RPC-only Setup 7-3 8 _________________________________________________________________ CICSSNACFG Migrating to the new SNA configuration utility The new SNA configuration utility requires a different configuration file setup from the default utility. If you are migrating from the original utility, you have a cicssnaconfig.cfg configuration file in one or more CICS for Digital UNIX region directories. The information in this file must be migrated to the new format in order to use the replacement SNA utility. If you have not used the original utility before, and therefore have no cicssnacfg.cfg files, you do not need to perform any migration. The replacement SNA configuration utility uses three configuration files,not one: o locallu.cfg-local LU definitions o remotelu.cfg-remote LU definitions o mode.cfg-mode definitions To migrate your cicssnacfg.cfg file to the format required for the new utility, you must take the data in it and copy it to the three files used by the replacement utility. The configuration files for the replacement utility must reside in one of the following directories: o /var.cics_sna This provides a global definition for all regions on the system and the LU6.2 server. o /var/cics_region/region_name CICSSNACFG 8-1 CICSSNACFG This provides a definition for use only with the specific region. If you are maintaining files here, note the use of the -r flag on the command. Maintaining the files in one of the above directories provides a central point for managing the local SNA resources. The following example shows a simple cicssnaconfig.cfg file and the migrated locallu.cfg, remotelu.cfg and mode.cfg files. LOCAL_LU: LocalNetworkName = GBNETWRK LocalLUName = IYA1T0C0 LUSessionLimit = 60 SessionActivation = TRUE MaxSyncLevel = CONFIRM ServerTransport = TCPIP ServerNodeName = scotty.local.acme.com ServerID = LU62_SRV GatewayTransport = TCPIP GatewayCapability = PRIMARY_OR_SECONDARY GatewayAuthPwd = NULL GatewayNodeName = scotty.local.acme.com REMOTELU: RemoteNetworkName = GBNETWRK RemoteLUName = IYL43 InitiateType = INITIATE_ONLY ParalSessSupp = 1 CNOSSupport = 1 LULUPassword = NULL TransmissionGroup = TransGrp SecurityAccept = NONE ServerTransport = TCPIP ServerNodeName = scotty.local.acme.com ServerID = LU62_SRV 8-2 CICSSNACFG CICSSNACFG MODE: ModeName = CICSISC0 SndMaxRUSizeLowBound = 256 SndMaxRUSizeUpBound = 1024 RcvMaxRUSizeLowBound = 256 RcvMaxRUSizeUpBound = 1024 SingleSessReinit = UNDEFINED ConWinAutoActLim = 5 MinConWinSource = 5 MinConWinTarget = 5 PrefRecvRUSize = 512 PrefSendRUSize = 512 LocalMaxSessLim = 10 CICSSNACFG 8-3 CICSSNACFG The conversion of the above file would result in the three files as shown below: # :m6 LocalNetworkName="" LocalLUName="" LUSessionLimit=60 SessionActivation=TRUE MaxSyncLevel=CONFIRM ServerTransport=TCPIP ServerNodeName="" ServerID=LU62_SRV GatewayTransport=TCPIP GatewayCapability=PRIMARY_OR_SECONDARY GatewayAuthPwd=NULL GatewayNodeName="" IYA1T0C0: LocalNetworkName=GBNETWRK LocalLUName=IYA1T0C0 LUSessionLimit=60 SessionActivation=TRUE MaxSyncLevel=CONFIRM ServerTransport=TCPIP ServerNodeName=scotty.local.acme.com ServerID=LU62_SRV GatewayTransport=TCPIP GatewayCapability=PRIMARY_OR_SECONDARY GatewayAuthPwd=NULL GatewayNodeName=scotty.local.acme.com 8-4 CICSSNACFG CICSSNACFG :m6 RemoteNetworkName="" RemoteLUName="" InitiateType=INITIATE_ONLY ParalSessSupp=1 CNOSSupport=1 LULUPassword=NULL TransmissionGroup=TransGrp SecurityAccept=NONE ServerTransport=TCPIP ServerNodeName="" ServerID=LU62_SRV IYL43: RemoteNetworkName=GBNETWRK RemoteLUName=IYL43 InitiateType=INITIATE_ONLY ParalSessSupp=1 CNOSSupport=1 LULUPassword=NULL TransmissionGroup=TransGrp SecurityAccept=NONE ServerTransport=TCPIP ServerNodeName=scotty.local.acme.com ServerID=LU62_SRV :m6 ModeName="" SndMaxRUSizeLowBound=256 SndMaxRUSizeUpBound=1024 RcvMaxRUSizeLowBound=256 RcvMaxRUSizeUpBound=1024 SingleSessReinit=UNDEFINED ConWinAutoActLim=5 MinConWinSource=5 MinConWinTarget=5 PrefRecvRUSize=512 PrefSendRUSize=512 LocalMaxSessLim=10 CICSSNACFG 8-5 CICSSNACFG CICSISC0: ModeName=CICSISC0 SndMaxRUSizeLowBound=256 SndMaxRUSizeUpBound=1024 RcvMaxRUSizeLowBound=256 RcvMaxRUSizeUpBound=1024 SingleSessReinit=UNDEFINED ConWinAutoActLim=5 MinConWinSource=5 MinConWinTarget=5 PrefRecvRUSize=512 PrefSendRUSize=512 LocalMaxSessLim=10 It is important to note that with the default utility there was an association between local and remote LUs and modes which was determined by their relative ordering in the cicssnaconfig.cfg file. There is no such concept of association with the replacement utility. In order to provide association, a script must be written which executes the utility for each (local LU, remote LU, mode) combination. Using the Replacement New Configuration Utility The new SNA configuration utility provides an interface capable of: o Defining, deleting, updating and viewing the Local SNA LU6.2 server's local LU, remote LU and mode definitions. o Updating the SNA domain gateway and SNA peer server databases when the corresponding Local SNA LU6.2 server definitions are updated. o Acquiring and releasing LU6.2 sessions. In the following description, the "permanent database" refers to the configuration files used by the replacement utility. No other existing CICS files are affected. The "runtime database" refers to the Local SNA LU6.2 server and SNA domain gateway or SNA peer server. 8-6 CICSSNACFG CICSSNACFG cicssnacfg [-r regionName] [-c {locallu|remotelu|mode}] [-P|-R|-B] [-a {add|delete|update|get|acquire_mode|release_mode}] [-t] [-f] [-v] [[type=name]...] [resourceName] [[attributeName=attributeValue]...] cicssnacfg -? CICSSNACFG 8-7 CICSSNACFG The flags are defined as follows: -r region This is used to specify the region name, and hence the location of the configuration files. If a region name is not supplied, the default location is taken to be /var/cics_sna. -c class Use this option to specify a class. A class can be one of the following: locallu To update the local LU definitions remotelu To update the remote LU definitions mode To update the mode LU definitions -P -R -B These flags are used to specify the database to be updated: -P Accesses the permanent database configuration files only. This is the default option. -R Accesses the runtime database, that is, the Local SNA LU6.2 server and SNA domain gateway or SNA peer server. -B Accesses both the permanent and runtime databases. -a Use this option to specify an action. An action can be one of the following: 8-8 CICSSNACFG CICSSNACFG add Adds a resource definition of a given class to the permanent database, and may install a resource definition into the runtime database. This action initialises the data structures for the resource with the default values from the reserved resource default, before overwriting them with your specified values. delete Deletes a resource definition of a given class from the permanent database, and may delete a resource definition from the runtime database. update Updates a resource definition of a given class in the permanent database, and may update a resource definition in the runtime database. This action initialises the data structures for the resource with the values from the specified resource definition, before overwriting them with your specified updated values. get Fetches and displays resource attributes of a given class from the permanent database, or the runtime database if specified. acquire_ Acquires the sessions in a specified mode- mode group. The SNASVCMG sessions are also acquired automatically if necessary. release_ Releases the sessions in a specified mode- mode group. -t Used only when the release_mode action is used. This flag indicates that all modes are to be released, and not just the modeName specified. On parallel session connections, this has the effect of releasing the connection. -f CICSSNACFG 8-9 CICSSNACFG Used only when the release_mode action is used. This flag indicates that the "force" option is to be used on the release_mode action. -v Sets the "verbose" option, which generates more messages during the processing of the command. Without this option, the only messages which are output are error messages. type=name The "type" can be LOCALLU, REMOTELU or MODE. This is used to specify the associated resources when required. resourceName The name of the resource of the specified class, upon which you wish to perform the specified action. attributeName=attributeValue These are the override options when adding or updating resources. The attributeName must be correct for the specified class. If no overrides are specified, then the default options are taken. -? Displays the usage message for cicssnacfg. The following examples show typical usage of cicssnacfg. Defining LUs and modes To define a locallu, for example: cicssnacfg -a add -c locallu IYA1T0C9 LocalLUName=IYA1T0C9\ ServerNodeName=scotty.local.acme.com\ GatewayNodeName=scotty.local.acme.com To define a remotelu: cicssnacfg -a add -c remotelu IYL42 ServerNodeName=scotty.local.acme.com 8-10 CICSSNACFG CICSSNACFG To define a mode: cicssnacfg -a add -c mode CICSISC0 Note that the above examples only define the resources to the permanent database. In order to also define resources to the runtime database (that is, the SNA LU6.2 server and Peer Server), the -R (or -B) option must be used. The following examples demonstrate how to define resources to the runtime database (note the differences from the above examples for remotelu and mode): To define a locallu: cicssnacfg -a add -c locallu -R IYA1T0C9 LocalLUName=IYA1T0C9\ ServerNodeName=scotty.local.acme.com\ GatewayNodeName=scotty.local.acme.com To define a remotelu: cicssnacfg -a add -c remotelu -R LOCALLU=IYA1T0C9 IYL42\ ServerNodeName=scotty.local.acme.com To define a mode: cicssnacfg -a add -c mode -R LOCALLU=IYA1T0C9 REMOTELU=IYL42\ CICSISC0 When defining a remotelu to the runtime database, you must specify the associated locallu, and when defining a mode, you must specify the associated locallu and remotelu. Displaying LU and mode information Information about specific LUs or modes can be displayed from either the permanent or runtime databases. The same type of information is displayed in each case. The following command retrieves information on a defined resource from the permanent database: cicssnacfg -a get -c locallu IYA1T0C9 CICSSNACFG 8-11 CICSSNACFG The following command retrieves information on a defined resource from the runtime database: cicssnacfg -a get -c remotelu -R LOCALLU=IYA1T0C9 IYL42 8-12 CICSSNACFG CICSSNACFG Updating LU and mode definitions After you have defined resources to the permanent database, they can be updated to modify specified attributes on the definition. Then you specify the update in much the same way as when adding a resource, and you specify attributeName=attributeValue pairs for the attributes you wish to modify. The following examples show a modification in the permanent database: cicssnacfg -a update -c locallu IYA1T0C9 SessionActivation=FALSE The runtime database definition of a resource may also be updated: cicssnacfg -a update -c remotelu -R LOCALLU=IYA1T0C9 IYL42 Note that a resource definition must already exist (in either permanent or runtime databases) in order for it to be updated. Deleting LU and mode definitions After you have defined resources to the permanent database, they can be deleted when no longer required. A previously defined resource can be deleted from either the runtime or permanent database, or both. To delete an entry from the permanent database: cicssnacfg -a delete -c mode CICSISC0 To delete an item from the runtime database: cicssnacfg -a delete -c mode -R LOCALLU=IYA1T0C9 CICSISC0 Acquiring sessions When you have your resources defined (at least in the permanent database) you can acquire the mode group on a connection. To do this, you must specify the mode, remotelu and locallu. You may specify all three on the command line, or if you wish you can omit one or more of the resources CICSSNACFG 8-13 CICSSNACFG from the command line and the cicssnacfg will take the first resource from the appropriate configuration file. ________________________ Note ________________________ You must acquire sessions each time you restart CICS, or when the connection has become released. ______________________________________________________ In previous examples, the following resources were defined: a locallu IYA1T0C9, a remotelu IYL42, and a mode CICSISC0. To acquire a mode on a connection, you can issue one of the following commands: cicssnacfg -a acquire_mode This uses the first locallu, remotelu and mode that it finds in the configuration files. cicssnacfg -a acquire_mode LOCALLU=IYA1T0C9 REMOTELU=IYL42 MODE=CICSISC0 This explicitly sets the resources from the command line. cicssnacfg -a acquire_mode LOCALLU=IYA1T0C9 REMOTELU=IYL42 This will take the first mode definition it finds in the mode configuration file. Releasing sessions To release a mode group on a connection, issue the following: cicssnacfg -a release_mode LOCALLU=IYA1T0C9 REMOTELU=IYL42 MODE=CICSISC0 Again, the same rules apply as for acquire_mode action. Note that for parallel session connections, the releasing of one mode group will not release the connection. To release the connection you need to release ALL mode groups. To do this, issue: cicssnacfg -a release_mode -t LOCALLU=IYA1T0C9 REMOTELU=IYL42 MODE=CICSISC0 8-14 CICSSNACFG CICSSNACFG The -t option instructs cicssnacfg to release all mode groups, thus releasing the connection. Lastly, there is the simplest method of configuring a connection. This is the method which most likely will be used each time the connection is to be established, and is the default action. cicssnacfg This takes the first resource from each of the configuration files and defines it to the LU6.2 server. It then acquires the mode group for the connection. You may override this default action by specifying LOCALLU=, REMOTELU= or MODE= on the command line: cicssnacfg LOCALLU=IYA1T0C9 REMOTELU=IYL42 MODE=CICSISC0 If you have multiple modes, remotelus or locallus, then you could create a script which contained multiple calls to cicssnacfg - one for each locallu/remotelu/mode combination. Tracing the utility If you set CICSTRACE=1 in your environment before running cicssnacfg, then it will generate CICS product trace which can be formatted with the cicstfmt utility. CICSSNACFG 8-15