IBM Software Group Using CICS Dynamic Scripting Jonathan Lawrence (jlawrence@uk.ibm.com) Software Developer CICS Dynamic Scripting 11 January 2011 WebSphere Support Technical Exchange
Agenda Overview and summary of previous WSTE session Review some material from previous session Using CICS Dynamic Scripting Zero programming model Configuration Interacting with CICS Restrictions of CICS Dynamic Scripting Some potential pitfalls Summary and Questions WebSphere Support Technical Exchange 2 of 31
Overview of previous WSTE session WebSphere Support Technical Exchange 3 of 31
Introduction to CICS Dynamic Scripting Session presented on 12 October 2010 Replay and demo available via: http://www.ibm.com/support/docview.wss?uid=swg27019845 Topics covered: Overview and key features Architectural overview Installation and configuration Demo of basic administration Zero programming model WebSphere Support Technical Exchange 4 of 31
Using Dynamic Scripting: Basic Concepts WebSphere Support Technical Exchange 5 of 31
Basic Concepts IBM Software Group Zero Programming Model Events Global Context Notes on PHP Support Zero modules Resolving applications (dependency management) Virtual Directories REST support Configuration: zero.config and zerocics.config Interacting with CICS WebSphere Support Technical Exchange 6 of 31
Events All behaviour in the system is modelled as a set of events Applications are built by handling these events and providing desired behaviour For example, these events are fired when a normal HTTP request is received: The zero programming model is single-threaded: events are fired sequentially on the same thread. WebSphere Support Technical Exchange 7 of 31
The Global Context It s a map of data Language-agnostic Used for passing data between events, for storing application state Zones define the lifetime and visibility of the data Event Zone Request Tmp Config User App Storage Scope/Visibility All handlers for a single event All handlers along the path of a single request All requests for all users of the application All requests all users All request for a particular user (HTTP Session equivalent) All requests for all users of the application All requests for all users of the application Non-persistent Spot the zget() & zput() calls in the next demo! Persistent WebSphere Support Technical Exchange 8 of 31
PHP Support The PHP engine is written in Java. Compiles PHP into Java bytecode to run on the Java Virtual Machine. Does not support all PHP functions and extensions available for the original PHP engine from php.net, but can run many popular apps: phpbb, WordPress, SugarCRM See projectzero.org for limitations: http://www.projectzero.org/zero/monza/latest/docs/zero.devguide.doc/zero.php/core.html PHP / Java bridge allows PHP code to call Java APIs directly: <?php java_import('java.util.hashmap'); $map = new HashMap; $map->put('data', array(1,2,3,4,5)); var_dump($map->get('data')); Import Java classes into PHP code Use them just like PHP classes More information: http://projectzero.org/php WebSphere Support Technical Exchange 9 of 31
Zero Modules All applications are modules Modules declare dependencies on other modules in config/ivy.xml: <dependencies> <dependency org="zero" name="zero.cics.core" rev="[1.0.0.0, 2.0.0.0["/> <dependency org="zero" name="zero.data" rev="[1.0.0.0, 2.0.0.0["/> <dependency org="zero" name="zero.mail" rev="[1.0.0.0, 2.0.0.0["/> </dependencies> Modules inherit all assets (scripts, static files, java classes) from their deps. In CICS Dynamic Scripting, all applications depend on zero.cics.core Provides the core CICS integration functionality Itself depends on zero.core, therefore pulls in the core standard zero functionality. Modules are not just for user apps: core functionality of zero and CICS Dynamic Scripting is implemented in zero modules. WebSphere Support Technical Exchange 10 of 31
Resolving Applications An application must be resolved before the it can be used. Resolving an app means: Locating its dependencies & determining exactly which versions to use. Possibly retrieving them from a remote repository, if they are not found in the app s workspace or the CLI s local repository. Two commands can resolve an app: zero resolve: attempts to locate the exact same versions of the dependencies that were used last time the module was resolved. zero update: resolves the app against the latest suitable versions of the modules available in the local repository. NB: These commands access a remote repository if no suitable version is found in the local repository. WebSphere Support Technical Exchange 11 of 31
Resolving Applications resolve and update look for modules in 1. The app s workspace, i.e. the parent directory of the app. Modules in the same workspace are referred to as peers 2. The CLI s local repository. $ZERO_HOME/zero-repository/<module_group_name> 3. Remote repositories. The CLI s current active module group defines which URIs will be searched. Ivy and Maven repositories are supported. Users can add repo URIs to module groups and create new module groups The default module group is called stable. More info on zero dependency & repository management: http://www.projectzero.org/smash/1.1.x/docs/zero.devguide.doc/zero.cli.tasks/dependencymanagement.html WebSphere Support Technical Exchange 12 of 31
Resolving Applications Once the app is resolved, the location of the dependencies is written to file: $APP_HOME/.zero/private/resolved.properties This information is used to load the application s classes. Most dependencies are not part of the classpath when the JVM is started. They are added dynamically at runtime during application initialisation. WebSphere Support Technical Exchange 13 of 31
Virtual Directories From the application developer s perspective, artefacts are inherited from dependencies. They are available through the concept of Virtual Directories. The Virtual Directory browser tool illustrates this. It can be added to any app by adding a dependency on the module zero.core.webtools. Files on zfs Virtual Directory view WebSphere Support Technical Exchange 14 of 31
What is REST? Representational State Transfer (REST) is the architectural model on which the World Wide Web is based Principles of REST: Resource centric approach All relevant resources are addressable via URIs Uniform access via a constrained set of actions, e.g. POST, GET, PUT, DELETE Content type negotiation allows retrieving alternative representations from same URI RESTful services are easy to access from code running in web browsers, any other client or servers. More information: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm WebSphere Support Technical Exchange 15 of 31
REST and Project Zero RESTful event handlers in Project Zero Each script in the <apphome>/app/resources directory is a resource handler URL convention for interacting with resources: /resources/<collectionname>[/<memberid>[/<pathinfo>]] URI and HTTP method define the resource to access and the action to perform Action can be taken on the entire collection, or a specified member of the collection Example: URI HTTP Method Event Description Resource Handler Function http://example.com/resources/people GET List people onlist() http://example.com/resources/people POST Create person oncreate() http://example.com/resources/people/john GET Retrieve person onretrieve() http://example.com/resources/people/john PUT Update person onupdate() http://example.com/resources/people/john DELETE Delete person ondelete() WebSphere Support Technical Exchange 16 of 31
Demo: Add dependency on zero.core.webtools, zero.cics.php Resolve & restart the app Access webtools UI to show Virtual Directories in action Add script which stores data in different zones to show Global Context Add basic RESTful event handler to show events, access with Poster WebSphere Support Technical Exchange 17 of 31
Configuration Files Two configuration files not to be confused. zero.config: contains general application configuration settings Every module has a zero.config file in $APP_HOME/config Part of zero programming model not specific to CICS Dynamic Scripting, also used in smash. JSON format. Example settings: application port numbers, custom event handlers, app-specific JVM options, custom settings to be added to global context config zone. Settings are inherited from dependencies zero.config (and can be overridden). zerocics.config: defines CICS Dynamic Scripting s relationship with CICS region Every CLI installation has a zerocics.config in $ZERO_HOME/config Specific to CICS Dynamic Scripting never used in plain WebSphere smash. Example settings: which CICS region to use, which CICS user IDs, CICS resource attributes. Can be overridden on a per-app basis, but settings are not merged or inherited from multiple locations. One of two possible files is used exclusively: $APP_HOME/config/zerocics.config is used if it is present. Otherwise, $ZERO_HOME/config/zerocics.config is used. WebSphere Support Technical Exchange 18 of 31
Interacting with CICS from an Application PHP and Groovy scripts can interact with CICS using the JCICS Java API Groovy code can interact with Java APIs natively. PHP code can use the PHP/Java Bridge. JCICS JavaDoc: https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/com.ibm.cics.ts.smash.doc/welcome/welcomepage.html See Dynamic Scripting InfoCenter doc for examples. WebSphere Support Technical Exchange 19 of 31
Limitations Some restrictions in Dynamic Scripting in CICS compared to WebSphere smash Not all smash modules supported Some config settings not supported Automatic App recycling not supported Some PHP extensions not supported Not all JCICS API s supported XCTL, Web Send, 3270, APPC Some minor differences in HTTP behaviour between Dynamic Scripting in CICS and WebSphere smash on other platforms See Dynamic Scripting for CICS Info Center for more details WebSphere Support Technical Exchange 20 of 31
Potential Pitfalls WebSphere Support Technical Exchange 21 of 31
Common Issues See Troubleshooting doc: http://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.smash.doc/troubleshooting.html Examples: Pre-reqs missing or not correctly configured UNIX file permission issues EXCI connectivity problems (CICS not up, incorrect STEPLIB environment variable, incorrect SVC number ) App is missing dependency on a required module (zero.cics.core, zero.cics.php) Attempts to use smash features not yet supported in CICS Dynamic Scripting App transferred from smash to CICS with package standalone option Zero programming model issues (not specific to CICS Dynamic Scripting) See docs and forums on projectzero.org JVMServer heap size configuration issues. Encoding issues. WebSphere Support Technical Exchange 22 of 31
Common Issues : Encoding Considerations Character Sets Programs often convert between bytes and character data, e.g.: Writing/reading text to/from the file system Sending/receiving text over the network Such conversions always use a character set to map characters to byte values: Text é Charset ISO8859-1 UTF-8 Byte value [ 0xE9] [ 0xC3, 0xA9] WebSphere Support Technical Exchange 23 of 31
Common Issues : Encoding Considerations ASCII-compatible character sets and EBCDIC platforms Many common Western characters have the same byte value representation in all ASCIIcompatible character sets. Code that is tested only on ASCII platforms and only with such characters as input might ignore the issue of enforcing a specific encoding in all byte/string conversions. If the code assumes an ASCII character set will be used, it may behave unexpectedly when running in an EBCDIC environment. These characters have the same byte value in all ASCII-compatible Character sets. ASCII-compatible character sets (UTF-8, ISO8859-1, windows-1252...) h e l l o EBCDIC character sets (IBM-1047, IBM-037, IBM-277 ) [ 0x68, 0x65, 0x6C, 0x6C, 0x6F] [0x88, 0x85, 0x93, 0x93, 0x96] WebSphere Support Technical Exchange 24 of 31
Common Issues : Encoding Considerations Never rely on Java s default character set In Java, if no Charset is specified on a byte[] String conversion, a platform-specific default is used. The default can be overridden with the file.encoding system property, but some JCICS library APIs currently require that the default is left unchanged. Therefore, Dynamic Scripting apps run on JVMs that default to EBCDIC but many 3 rd Java libraries assume they are running on JVMs that default to ASCII! Consider the following call, which sends bytes over the network. If the recipient is expecting ISO8859-1 bytes, this call will work as expected on ASCII platforms, but not in CICS Dynamic Scripting: connection.getoutputstream().write("hello".getbytes()); A portable equivalent would be: connection.getoutputstream().write("hello".getbytes("iso8859-1")); Pay particular attention if the application invokes 3 rd party Java libraries. Most 3 rd party Java code has not been tested on EBCDIC platforms. WebSphere Support Technical Exchange 25 of 31
Common Issues : Encoding Considerations Other Encoding Considerations: All script files, configuration files etc read by the zero platform must be UTF-8. All log files generated by the zero platform are UTF-8. Groovy introduces more convenience methods that use the default encoding. e.g. File.getText() In the PHP language, there is no distinction between strings and byte arrays. String literals are arrays of UTF-8 bytes. Pay particular attention to encoding issues when passing PHP strings to Java methods over the PHP/Java bridge (see doc). See doc for more information: http://publib.boulder.ibm.com/infocenter/cicsts/v4r1/topic/com.ibm.cics.ts.smash.doc/smash_dynamicscripting_encodingconsiderations.html WebSphere Support Technical Exchange 26 of 31
Summary CICS Dynamic Scripting embeds Project Zero technology into CICS Transaction Server v4.1 Runs in the new CICS JVMSERVER multi-threaded JVM environment. Tightly coupled with the CICS environment allowing access to conventional CICS resources (Programs, Data etc.) Administration is via the z/os UNIX command line using zero CLI commands. CICS Web Support replaces the web server layer from conventional Zero applications. Some restrictions & differences exist between the CICS Dynamic Scripting environment and Project Zero. WebSphere Support Technical Exchange 27 of 31
CICS Dynamic Scripting Resources WebSphere Support Technical Exchange presentation and demo: Introduction to CICS Dynamic Scripting in CICS Transaction Server v4.1 http://www.ibm.com/support/docview.wss?uid=swg27019845 Learn about the CICS Transaction Server Feature Pack for Dynamic Scripting in the CICS Transaction Server v4.1 InfoCenter: https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp? topic=/com.ibm.cics.ts.smash.doc/welcome/welcomepage.html Learn about the Project Zero technology embedded in CICS Dynamic Scripting in the Project Zero website: http://www.projectzero.org/cics/ Access details of sample applications for CICS Dynamic Scripting (some CICS specific and some general): http://www.projectzero.org/wiki/development/cicssamples WebSphere Support Technical Exchange 28 of 31
Additional Product Resources WebSphere and CICS Support blog https://www.ibm.com/developerworks/mydeveloperworks/blogs/aimsupport/?lang=en IBM_CICS support news on Twitter http://www.ibm.com/support/docview.wss?uid=swg21384915 Track specific CICS APARs or CICS APARs by component id http://www.ibm.com/support/docview.wss?uid=swg21422149 Sign up to receive technical support e-mails http://www.ibm.com/software/support/einfo.html CICS Featured documents http://www.ibm.com/support/docview.wss?uid=swg27006900 Webcasts for CICS and OMEGAMON http://www.ibm.com/support/docview.wss?uid=swg27007244 CICS Transaction Server Support Web page http://www.ibm.com/support/entry/portal/overview/software/other_software/cics_transaction_server WebSphere Support Technical Exchange 29 of 31
We Want to Hear From You! Tell us about what you want to learn Suggestions for future topics Improvements and comments about our webcasts We want to hear everything you have to say! Please send your suggestions and comments to: wsehelp@us.ibm.com WebSphere Support Technical Exchange 30 of 31
Questions and Answers WebSphere Support Technical Exchange 31 of 31