About This Book
The XML Services User’s Guide documents the most commonly used features of the XML Services application programming interface (API) to ChangeMan® ZMF. Tutorials, code examples, use cases, and tips and techniques for applications supplement detailed data structure tables covering 162 functions available for general customer use.
Services used with the Enterprise Release Option (ERO) are not described in this guide but are listed for reference in ERO XML Services Summary. Refer to the ChangeMan ZMF ERO XML Services User’s Guide for information on using these services.
After reading this guide, you should be able to do the following:
-
Understand the software architecture that underlies ChangeMan ZMF XML Services.
-
Create a well-formed XML document that complies with Serena XML syntax.
-
Use the Serena XML markup language to build reusable XML documents that invoke functions and retrieve data from ChangeMan ZMF.
-
Use the XML batch execution client to issue Serena XML service requests to ChangeMan ZMF and receive Serena XML replies.
-
Experiment with the XMLSERV interactive prototyping tool to learn Serena XML syntax, generate prototype request messages, and browse Serena XML replies.
Software Versions
This guide discusses Serena Software’s XML Services as implemented in ChangeMan ZMF version 8.1 (GA) and ChangeMan ZDD 8.1 (GA) and later.
Audience
This guide targets experienced ChangeMan ZMF programmers, multi-platform systems integrators, and ChangeMan ZMF administrators.
You should be familiar with your mainframe operating system and security system, and you should understand the operation and administration of ChangeMan ZMF. Some familiarity with basic XML syntax and schemas is helpful. Familiarity with PCs is assumed.
Scope
The XML Services features described in this guide are limited to services and functions available for general customer use. These are sometimes called the “Green” services. “Green” functions address package and component lifecycle management, complex searches and queries, data set management functions, change library management functions, and detailed information retrieval from the ChangeMan ZMF database.
Additional services and functions exist to support advanced systems integration needs. The latter features are known as the “Yellow” services because they pose some risk of database corruption and should be used with caution. These are documented in quick-reference form for customers who attend advanced training in XML Services. This information is available from Serena Customer Support.
Related Topics
You need not become an XML expert to use XML Services. To master its advanced capabilities, however, sound knowledge of XML standards is advised. The authoritative source for this information is the World Wide Web Consortium (W3C) (http://www.w3c.org/).
The eXtensible Markup Language (XML) standard consists of many components in various stages of development, change, and ratification. Of these, you should become familiar with the core XML specifications that cover XML syntax and schemas. If you want to manipulate and reformat the XML output from XML Services (e.g., for custom reports), you should also study the XML stylesheet (XSL) specifications.
Related Documents
| Title | Description |
|---|---|
| ChangeMan® ZMF ERO XML Services User’s Guide | Documents the most commonly used ERO features of the XML Services application programming interface to ChangeMan ZMF. |
| ChangeMan® ZMF XML Reference Tables | HTML cross-reference tables for “green” and “yellow” service/scope/message combinations supported by XML Services, including ERO, and the XML tags for each. If you have taken Serena’s advanced training course in XML Services, you can contact Customer Support for access to this guide. |
| ChangeMan® ZMF Installation Guide | Step-by-step instructions for the initial installation of ChangeMan ZMF. Includes installation instructions for XML Services working data |
| ChangeMan® ZMF Administrator’s Guide | Includes information on customizing exits to call XML Services. |
| ChangeMan® ZMF Web Services *Getting Started Guide | Documents the Web Services application programming interface to ChangeMan ZMF |
Typographical Conventions
The following typographical conventions are used in the online guides and online help. These typographical conventions are used to assist you when using the documentation; they are not meant to contradict or change any standard use of typographical conventions in the various product components or the host operating system.
| Convention | Explanation |
|---|---|
| italics | Introduces new terms that you may not be familiar with and occasionally indicates emphasis. |
| UPPERCASE | Indicates keys or key combinations that you can use. For example, press ENTER. |
monospace |
Indicates syntax examples, values that you specify, or results that you receive. |
monospace italics |
Indicates names that are placeholders for values you specify; for example, filename. |
| vertical rule | | Separates menus and their associated commands. For example, select File | Copy means to select Copy from the File menu. Also, indicates mutually exclusive choices in a command syntax line. |
Manual Organization
| This chapter . . . | Contains this information . . . |
|---|---|
| XML Services Concepts and Architecture | Introduction to features, functions, and benefits of XML Services. Layered software architecture, dynamic client/server messaging, XML interface language, and modular service objects. Choice of XML, COBOL copybook, or REXX batch execution clients. |
| XML Syntax Basics | XML language extensions and XML schemas. Syntax and structure of a well-formed XML document. High-level structure and syntax of Serena XML message documents. Table of Serena XML service, scope, and message names with corresponding COBOL copybooks. |
| Package Management | Serena XML syntax, data structures and values, code examples, and usage tips for the following package-related tasks: Package lifecycle functions (e.g., create, delete, freeze, submit, approve, promote, demote, back out, revert). Package-level component change (e.g., unfreeze, refreeze, list). Package control and metadata information management (e.g., list). |
| Component Management | Serena XML syntax, data structures and values, code examples, and usage tips for the following component tasks: Component lifecycle functions (e.g., checkout, checkin, browse, compare, build, recompile, relink, scratch, rename, lock, unlock). Component staging versions (e.g., list, retrieve). Component control and metadata information management (e.g., list). Component history information (e.g., selective search and list). |
| Search, Summary, and Analysis Tasks | Information retrieval and statistical analysis that crosses package, component, and/or application boundaries. Includes the following: Multi-package search (e.g., general and limbo search). Multi-package summary statistics. Component impact analysis functions. Change log creation and listing. |
| Dataset Management | XML Services support for managing sequential and partitioned datasets on the mainframe. Includes PDS/PDSE lifecycle functions (e.g., create and delete data set, delete data set member, and list data set information). |
| Hierarchical File System Services | XML Services support for managing HFS files and directories on the mainframe. Includes: HFS directory services (e.g., create, delete, rename, or list the contents of a directory). HFS file lifecycle services (e.g. create, delete, rename, or copy an HFS file, change certain file attributes, or test for file existence and verify user access permissions). File conversion services (e.g., import a z/OS PDS (Partitioned Data Set) member as an HFS file or export an HFS file as a PDS member). |
| Database Management for IMS and DB2 | Serena XML syntax and data structures for retrieval of change control metadata about the following: IMS package-level, application-level, and global settings and data binding information (e.g. control region, ACB build statement, DBD and PSB control statement list.) DB2 application-level and global settings and data binding information (e.g., list records for active DB2 applications, logical files, and physical files). |
| Online Forms Management | Serena XML syntax and data structures for retrieving information and submitting and approving custom online forms associated with a package. |
| ChangeMan ZMF Administration Tasks | Serena XML syntax and data structures for retrieving global and application-level information about change libraries, sites, languages, library types, and build procedures. XML access to site calendars and package installer scheduling facilities, approver maintenance, reason code administration, and notifications are also discussed. |
| System Environment Information | Serena XML syntax and data structures for retrieving SERNET and ChangeMan ZMF setup information, environment parameters, and started task library concatenation. |
| XMLSERV - Interactive XML Prototyping Tool | Interactive TSO/ISPF prototyping tool for XML Services. |
| SERXMLBC - Executing Native XML Service Calls | Serena XML native-XML batch execution client. |
| SERXMLAC - Calling XML Services from Assembler | Serena XML ASSEMBLER execution client. |
| SERXMLCC - Calling XML Services from COBOL | Serena XML COBOL execution client. |
| SERXMLRC - Calling XML Services from REXX | Serena XML REXX execution client. |
| Problem Analysis and Troubleshooting Tools | How to resolve errors when using XML Services. |