Skip to content

Package Lifecycle Tasks

Serena XML supports the following package lifecycle tasks for general use:
Create a Package - PACKAGE SERVICE CREATE Demote a Package with Cleanup - PACKAGE CLEANUP DEMOTE
Delete a Package - PACKAGE SERVICE DELETE Approve a Package - PACKAGE SERVICE APPROVE
Freeze a Package - PACKAGE SERVICE FREEZE List Package Installation Schedule - SCHEDULE SERVICE LIST
Submit a Package for JCL Build - PACKAGE SERVICE SUBMIT Hold Package Install Job - SCHEDULE SERVICE HOLD
Check a Package for Promotion Readiness - PACKAGE CHECK PROMOTE Release Package Install Job - SCHEDULE SERVICE RELEASE
Promote a Package - PACKAGE SERVICE PROMOTE Back Out a Package - PACKAGE SERVICE BACKOUT
Lock Promotion Site for Package - PACKAGE PROMOTE LOCK Revert a Package - PACKAGE SERVICE REVERT
Demote a Package - PACKAGE SERVICE DEMOTE

Create a Package - PACKAGE SERVICE CREATE

The package create message in Serena XML creates an empty change package in the staging area. A parent application must already exist to provide default settings for the new package.

The Serena XML service/scope/message tags and attributes for a package creation message are:

<service name="PACKAGE">
<scope name="SERVICE">
<message name="CREATE">

These tags appear in both requests and replies.

PACKAGE SERVICE CREATE Requests

The Serena XML syntax for a package creation request varies with the creation method you select. Three creation methods exist:

  • Short Method — Supplies only the minimum information required by the package master database. Complete information is supplied later via package updates using the ChangeMan ZMF ISPF interface. (Serena XML does not support updates to package master records for general use.)

  • Copy Forward (or Clone) Method — Copies values from a preexisting model package into the new package master entry. Changes are made later via package updates using the ChangeMan ZMF ISPF interface. (Serena XML does not support updates to package master records for general use.)

  • Long Method — Supplies all package master information in a single step. No subsequent updates are required. If you want to set the values of any user-defined variables for a package, you must use this method of package creation.

Choose a creation method using the <createMethod> subtag of the <request> message.

Example XML — PACKAGE SERVICE CREATE Request.

<?xml version="1.0"?> 
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="CREATE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
        <request>
            <applName>ACTP</applName>
            <createMethod>0</createMethod>
            <packageLevel>1</packageLevel>
            <packageType>1</packageType>
            <reasonCode>000</reasonCode>
            <requestorDept>IDD</requestorDept>
            <requestorName>USER24</requestorName>
            <requestorPhone>555 5555</requestorPhone>
            <packageTitle> TEST XML PACKAGE SERVICE CREATE</packageTitle>
            <packageDesc>TEST XML PACKAGE SERVICE CREATE</packageDesc>
            <packageImplInst>TEST XML PACKAGE SERVICE CREATE</packageImplInst>
            <siteInfo>
                <siteName>SERT8</siteName>
                <installDate>20091231</installDate>
                <fromInstallTime>0100</fromInstallTime>
                <toInstallTime>0200</toInstallTime>
                <contactName>USER24</contactName>
                <contactPhone>555 5555</contactPhone>
                <alternateContactName>USER24</alternateContactName>
                <alternateContactPhone>555 5555</alternateContactPhone> 
            </siteInfo>
        </request>
        </message>
    </scope>
</service>

...

The foregoing example requests the creation of a simple, planned, permanent package using the “short" method. The package is part of the “ACTP" application. Installation is scheduled for one production sites.

As the example illustrates, the <siteInfo> tag represents a complex data element A complex data element consists of other XML tags, rather than simple data. Such markup syntax, which potentially nests tags within tags within tags to any depth, is how XML implements its hierarchical tree data structure in a text data stream.

In addition, <siteInfo> is a repeatable tag. A repeatable tag allows a variable number of consecutive repetitions to accommodate multiple instances of similarly structured information. For example, <siteInfo> can be repeated for each site where the newly created package will be installed. Repeatable tags enhance scalability in XML data structures.

Note that the XML data structures for package request and reply messages do not specify any particular order for the occurrence of tags. You must rely on tag name rather than tag ordinal position in a sequence to convey information to ChangeMan ZMF. Sequence within a data structure is not preserved.

For example, a package may be installed across multiple sites in any order. This is not necessarily the order you list your <siteInfo> data elements. Similarly, if you schedule multiple predecessor jobs to occur before package install, they may execute in any order so long as they precede package installation. You cannot assume that predecessor jobs will execute in the order you list them in your XML request.

Caution

Tag sequence is not preserved in package request and reply messages using Serena XML. Use tag names rather than tag ordinal position in a sequence to convey information to ChangeMan ZMF.

Data structure specifications for the package creation <request> tag appear in Exhibit 4-1

Exhibit 4-1. PACKAGE SERVICE CREATE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<affectedApplName> Optional 0 - ∞ String (4), variable Name of application affected by one or more participating packages in this complex/super package. Repeatable for multiple applications.
NOTE: Valid only for complex or super packages.
NOTE: If <partPackageName> used, at least one instance of this tag is required.
<applName> Required 1 String (4), variable Parent application name for new change package.
<complexSuperPackage> Optional 0 - 1 String (10), variable Name of complex/super package to which a participating package belongs.
NOTE: Valid only when creating a participating package.
NOTE: Required if <packageLevel> value is 4.
<complexSuperPackageAppl> Optional 0 -1 String (4), variable Application name of model package. Same as <complexSuperPackage> tag’s first 4 bytes.
<complexSuperPackage- Number> Optional 0 -1 Integer(6) Package ID of model package. Same as <complexSuperPackage> tag’s last 6 bytes.
<createMethod> Required 1 Integer (1) Package creation method code. Values:
0 = Short creation method
1 = Copy forward (clone) method
2 = Long creation method
NOTE: If <createMethod> value is 0, the following additional tags are required:
<packageTitle>, <packageLevel>, <packageType>, <schedulerType>, <requestorPhone>,<requestorName>, <problemActionCode>, <siteInfo>
NOTE: If <createMethod> value is 1, you must name the package to copy from in <packageModel>.
NOTE: If <createMethod> value is 2, you must supply all the tags needed when <createMethod> is 0, plus the following: <packageDesc>, <packageImplInst>, <problemActionCode>.
<otherProblemAction> Optional 0 -1 String (44), variable Text of “Other" instructions if installation problem occurs.
NOTE: Required when value of <problemActionCode> = 3.
<packageApplModel> Optional 0 -1 String (4), variable Application name of model package. Same as first 4 bytes of <packageModel>.
<packageDesc> Optional 0 - 46 String (72), variable Description of package contents. Multiple entries of 72 bytes each.
<packageImplInst> Optional 0 - 46 String (72), variable Package install & implementation instructions. Multiple tags of 72 bytes each.
NOTE: Order of repeated tags is not preserved. Add sequence numbers to text if steps must be performed in order.
<packageLevel> Optional 0 -1 Integer (1) Code for package complexity or level in hierarchy. Values:
1 = Simple package
2 = Complex package
3 = Super package
4 = Participating package
NOTE: If value = 2 or 3, the names of participating packages are required in the <partPackageName> tag.
NOTE: If value = 4, you must supply name of complex/super package in tag <complexSuperPackage>.
<packageModel> Optional 0 -1 String (10), variable Name of source package from which entries are copied forward (“cloned") to new package.
NOTE: This tag is required if value in <createMethod> = 1.
<packageNumberModel> Optional 0 -1 Integer(6) Package ID of model package. Same as last 6 bytes of <packageModel>.
<packageTitle> Optional 0 -1 String (255), variable Working title for package. Appears on most listings & reports.
<partPackageName> Optional 0 - ∞ String (10), variable Name of a participating package pointed to by this complex/super package record. Repeatable for multiple participating packages.
NOTE: Valid only when creating a complex or super package.
NOTE: Required if <packageLevel> value is 2 or 3.
NOTE: Tag <affectedApplName> is also required if this tag is used.
<problemActionCode> Optional 1 Integer (1) Code for action to take if problem occurs in package install. Values:
1 = Hold production & contact developer for instructions
2 = Back out change, then proceed with production
3 = Other instructions
NOTE: If value = 3, you must supply instructions in <otherProblemAction>.
<reasonCode> Optional 0 - 1 String (3), variable Customer-defined reason code for unplanned package installation.
NOTE: Required if <packageType> value is 3 or 4.
NOTE: Reason codes defined separately by ZMF administrator.
<release> Optional, for ERO 0 -1 String (8) Name of ERO release with which package is associated.
<releaseArea> Optional, for ERO 0 -1 String (8) Name of starting release area for ERO release package check-in.
<requestorDept> Optional 0 -1 String (4), variable Workgroup or department code for package creator.
<requestorName> Optional 1 String (25), variable Name of developer or contact person responsible for package.
<requestorPhone> Optional 1 String (15), variable Phone of developer or contact person responsible for package.
<schedulerType> Optional 1 Integer (1) Code for type of installation scheduler used with package. Values:
1 = ChangeMan scheduler
2 = Manual install
3 = Other automated scheduler
<schedulingInfo> Optional 0 - ∞ Complex See <schedulingInfo> subtag.
<siteInfo> Optional 0 - ∞ Complex See <siteInfo> subtag.
<tempChangeDuration> Optional 0 - 1 Integer (3) Number of days for temporary package to stay installed before automatic backout.
NOTE: Required if <packageType> value is 2 or 4.
<userVarLen101> . . . <userVarLen115> Optional 0 -1 each String (1) User-defined variables in ZMF. Total of 15 individually named, 1-byte tags supported.
NOTE: See topic “Package User Information" in the ChangeMan ZMF Customization Guide.
<userVarLen201> . . . <userVarLen211> Optional 0 -1 each String (2), variable User-defined variables in ZMF. Total of 11 individually named, 2-byte tags supported.
<userVarLen301> . . . <userVarLen310> Optional 0 -1 each String (3), variable User-defined variables in ZMF. Total of 10 individually named, 3-byte tags supported.
<userVarLen401> . . . <userVarLen410> Optional 0 -1 each String (4), variable User-defined variables in ZMF. Total of 10 individually named, 4-byte tags supported.
<userVarLen801> . . . <userVarLen810> Optional 0 -1 each String (8), variable User-defined variables in ZMF. Total of 10 individually named, 8-byte tags supported.
<userVarLen1601> . . . <userVarLen1605> Optional 0 -1 each String (16), variable User-defined variables in ZMF. Total of 5 individually named, 16-byte tags supported.
<userVarLen4401> . . . <userVarLen4405> Optional 0 -1 each String (44), variable User-defined variables in ZMF. Total of 5 individually named, 44-byte tags supported.
<userVarLen7201> . . . <userVarLen7205> Options 0 -1 each String (72), variable User-defined variables in ZMF. Total of 5 individually named, 72-byte tags supported.
<workChangeRequest> Optional 0 -1 String (12), variable Work order ID or change request number for package.

Tip

Tags: <userVarLen101> to <userVarLen7205>. See topic “Package User Information" in the ChangeMan ZMF Customization Guide.

The <schedulingInfo> and <siteInfo> tags both represent complex data elements — that is, they contain tags within tags. Their subordinate data structures are described below.

<schedulingInfo> Subtag

The <schedulingInfo> tag captures installation scheduling dependencies for a package. Each instance of the tag names a predecessor job and/or a successor job to run before and/ or after the installation of the newly created package. The <schedulingInfo> tag may be repeated as many times as needed to ensure that all installation prerequisites and follow-up tasks occur. Data structure details for the <schedulingInfo> tag appear in the following exhibit.

Exhibit 4-2. <schedulingInfo> Subtag Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<successorJobName> Optional 0 - 1 String (8), variable Must be valid job name for system where install takes place.
<predecessorJobName> Optional 0 - 1 String (8), variable Must be valid job name for system where install takes place.

<siteInfo> Subtag

The <siteInfo> tag provides the site name, contact information, and scheduled package installation date for a remote production site. The tag may be repeated as many times as needed to cover all sites where the newly created package will be installed. At least one instance of the tag is required in a package creation request that uses either the “short" or “long" create method. Data structure details for the <siteInfo> tag appear in the following exhibit:

Exhibit 4-3. <siteInfo> Subtag Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<siteName> Optional 0 - 1 String (8), variable Name of site where package will be installed.
<installDate> Optional 0 - 1 Date, yyyymmdd Planned site install date for package. No punctuation.
<fromInstallTime> Optional 0 - 1 Time, hhmmss Start time for period during which site installation of package is planned. 24-hour format, no punctuation.
<toInstallTime> Optional 0 - 1 Time, hhmmss End time for period during which site installation of package is planned. 24-hour format, no punctuation.
<contactName> Optional 0 - 1 String (25), variable Name of contact person at remote site to assist with install.
<contactPhone> Optional 0 - 1 String (15), variable Phone of contact person at remote site to assist with install.
<alternateContactName> Optional 0 - 1 String (25), variable Name of alternate contact person at remote site to assist with install.
<alternateContactPhone> Optional 0 - 1 String (15), variable Phone of alternate contact person at remote site to assist with install.

PACKAGE SERVICE CREATE Replies

The Serena XML reply message returns, at most, one <result> data structure, which reports basic information about the newly created package. Most importantly, the <result> supplies a unique package name assigned to the package by ChangeMan ZMF.

Following the <result> data structure is the standard <response> data structure, which indicates the success or failure of the XML request and provides a status message. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

An example Serena XML package creation reply for a simple, planned, permanent package follows. Tags in bold always occur in a reply. Repeatable tags appear twice for illustration. Data structure details for the package creation <result> tag appear in Exhibit 4-4

Example XML — PACKAGE SERVICE CREATE Reply

<?xml version="1.0"?> 
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="CREATE">
            <result>
                <package>ACTP000012</package>
                <applName>ACTP</applName>
                <packageId>000012</packageId>
                <packageLevel>1</packageLevel>
                <packageType>1</packageType>
                <packageStatus>6</packageStatus>
                <installDate>20091231</installDate>
            </result>
            <response>
                <statusMessage>CMN2100I - ACTP000012 change package has been created.</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>2100</statusReasonCode>
            </response>
        </message>
    <scope>
</service>

...

Exhibit 4-4. PACKAGE SERVICE CREATE <result> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
<installDate> Optional 0 - 1 Date, yyyymmdd Planned install date for package, or start date of range.
<package> Optional 0 - 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable New package ID number generated by ZMF. Same as last 6 bytes of package name.
<packageLevel> Optional 0 - 1 Integer (1) Code for package complexity level. Values:
1 = Simple package
2 = Complex package
3 = Super package
4 = Participating package
<packageStatus> Optional 0 - 1 String (1) Code for status of package in lifecycle. Values:
1 = Approved
2 = Backed out
3 = Baselined
4 = Complex/super pkg closed
5 = Deleted (memo delete)
6 = Development
7 = Distributed
8 = Frozen
9 = Installed
A = Complex/super pkg open
B = Rejected
C = Temporary change cycle completed
NOTE: Only values 6 or A should be returned for package create.
<packageType> Optional 0 - 1 String (1) Package install type code. Values:
1 = Planned permanent
2 = Planned temporary
3 = Unplanned permanent
4 = Unplanned temporary

...

Delete a Package - PACKAGE SERVICE DELETE

The package deletion function in Serena XML flags or unflags an entire package for deletion. Deletion (or undeletion) is logical rather than physical. Physical deletion of flagged packages occurs at a later time under ChangeMan ZMF control.

The Serena XML service/scope/message tags for a package deletion message are:

<service name="PACKAGE"> 
<scope name="SERVICE">
<message name="DELETE">

These tags appear in both requests and replies.

PACKAGE SERVICE DELETE Requests

Serena XML supports two kinds of delete requests against a package:

  • Logical (“Memo") Delete — Flags a package for physical deletion at a future time. Package must be in development status prior to memo deletion. To choose this option, enter “1" in the <processingOption> tag.

  • Logical Undelete — Removes deletion flag from a memo-deleted package. Assumes the package has not been aged past the scheduled, physical delete date and time. To choose this option, enter “2" in the <processingOption> tag.

The following example shows how you might code a logical delete request in Serena XML. Data structure details for the package deletion <request> tag appear in Exhibit 4-5

Example XML — PACKAGE SERVICE DELETE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="DELETE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <processingOption>1</processingOption>
                <package>ACTP000015</package>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-5. PACKAGE SERVICE DELETE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<processingOption> Required 1 Integer (1), fixed = Logical delete = Logical undelete

PACKAGE SERVICE DELETE Replies

No <result> data structure is returned in the package deletion reply message. However, the standard <response> data structure is returned to indicate the success or failure of the package deletion request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Freeze a Package - PACKAGE SERVICE FREEZE

On ChangeMan ZMF servers, a Serena XML package freeze request does two things:

  • It freezes the package against changes.

  • It builds the “.X node" staging library containing file-tailored JCL installation code.

For a freeze request to execute successfully, all of the following conditions must be met:

  • The package is in development status.

  • All components are active and are at the same promotion level.

  • Any online forms in the package have been approved.

In addition, ChangeMan ZMF normally requires that a package pass the audit process before a freeze request can execute successfully.

The Serena XML service/scope/message tags for a package freeze message are:

<service name="PACKAGE"> 
<scope name="SERVICE">
<message name="FREEZE">

These tags appear in both requests and replies.

PACKAGE SERVICE FREEZE Requests

Serena XML allows you to freeze a package with or without prior validation of the staging library. Unless you are completely certain that all components in the package are ready to be frozen, you should validate the staging library as part of your package freeze request.

Tip

To validate the staging library as part of a package freeze request, enter “1” in the <validationParm> tag.

The example below shows how you might code a package freeze request in Serena XML. Data structure details for the package freeze <request> tag follow in Exhibit 4-6

Example XML — PACKAGE SERVICE FREEZE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="FREEZE">
            <header>
                <subsys>8</subsys>
               <product>CMN</product>
            </header>
            <request>
                <package>ACTP000012</package>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-6. PACKAGE SERVICE FREEZE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
userVariable01 Optional 0 - 8 String (8), variable User variable 01
userVariable02 Optional 0 - 8 String (8), variable User variable 02
userVariable03 Optional 0 - 8 String (8), variable User variable 03
userVariable04 Optional 0 - 8 String (8), variable User variable 04
userVariable05 Optional 0 - 8 String (8), variable User variable 05
userVariable06 Optional 0 - 72 String (72), variable User variable 06
userVariable07 Optional 0 - 72 String (72), variable User variable 07
userVariable08 Optional 0 - 72 String (72), variable User variable 08
userVariable09 Optional 0 - 72 String (72), variable User variable 09
userVariable10 Optional 0 - 72 String (72), variable User variable 10
<validationParm> Optional 0 -1 Integer (1) 1 = Validate package readiness prior to freeze operation

Tip

Tags: <userVariable01> to <userVariable10>: See topic “Custom V01-V10 Variables" in the ChangeMan ZMF Customization Guide.

PACKAGE SERVICE FREEZE Replies

No <result> data structure is returned in the reply message for a package freeze request. However, the standard <response> data structure is returned to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Occasionally, a package may freeze successfully but the subsequent file tailoring and JCL build step may not complete. If this occurs, Serena XML provides a way of finishing the file tailoring step on its own.

Tip

Use Serena XML to submit a package for JCL build if the package freeze step is successful, but the subsequent file tailoring and JCL build step does not complete. (See Submit a Package for JCL Build - PACKAGE SERVICE SUBMIT.)

Submit a Package for JCL Build - PACKAGE SERVICE SUBMIT

The package service submit request submits a previously frozen package for stage file tailoring — that is, it builds (or rebuilds) the “.X node" staging library containing file-tailored JCL installation and backout code. It performs this task at the package level rather than the component level.

The Serena XML service/scope/message tags for a package submit message are:

<service name="PACKAGE">
<scope name="SERVICE">
<message name="SUBMIT">

These tags appear in both requests and replies.

When successful, this service submits a JOB with output similar to the following:

 SDSF  OUTPUT  DISPLAY  CMN8ADSP  S0786765  DSID      4 LINE 71            CO
 COMMAND INPUT ===>                                                       SCR
IEF285I   ZMFA.CMN8ADSP.S0786765.D0000106.?                SYSOUT
IEF285I   ZMFA.CMN8ADSP.S0786765.D0000107.?                SYSOUT
IEF373I STEP/        /START 2009065.0630
IEF374I STEP/        /STOP  2009065.0630 CPU        0MIN 00.47SEC        SRB
IEF375I  JOB/CMN8ADSP/START 2009065.0630
IEF376I J OB/CMN8ADSP/STOP  2009065.0630 CPU        0MIN 00.47SEC        SRB
    PROG=CMNASPFT,PARMS=PGMCMNVPIJB
0032ACTP0000138USER35 Y
READY
END
ChangeMan(R)       CMNVPIJB - 6.1.0 File Tailoring

Function : Package install JCL build
Subsystem: 8
Userid   : USER24
Package  : ACTP000013
Schedule : Y
Date/Time: 2009/03/06 06:30:10

CMN8700I - ACTP000013 Installation JCL Build service completed

...

PACKAGE SERVICE SUBMIT Request

The following example shows how you might code a package service submit request using Serena XML. Data structure details for the packageservice submit tags appear in Exhibit 4-7

Example XML — PACKAGE SERVICE SUBMIT Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="SUBMIT">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000013</package>
                <cmnSubSystemId>8</cmnSubSystemId>
                <requestor>USER24</requestor>
                <addSchedulerOption>Y</addSchedulerOption>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-7. PACKAGE SERVICE SUBMIT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<addSchedulerOption> Optional 0 - 1 String (1) Code to add installation scheduler record for automated scheduling system. Values: Y = Yes, add scheduler record N = No, don’t add record C = Conditional, add scheduler record only if build succeeds.
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<cmnSubSystemId> Optional 1 String (1) ZMF subsystem ID where package resides (for batch execution).
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<requestor> Optional 1 String (8), variable Must be valid TSO user ID on mainframe LPAR where ZMF subsystem resides.

PACKAGE SERVICE SUBMIT Replies

No <result> data structure is returned in the reply message to a package submit request. However, the standard <response> data structure is returned to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Check a Package for Promotion Readiness - PACKAGE CHECK PROMOTE

The promotion check function determines whether a promote request is valid without performing the actual promotion. It ensures that the components to be promoted are active, the requested promotion library is a valid one for the requestor, and the package complies with administrator-defined promotion business rules.

The Serena XML service/scope/message tags for a promotion check message are:

<service name="PACKAGE"> 
<scope name="CHECK">
<message name="PROMOTE">

These tags appear in both requests and replies.

PACKAGE CHECK PROMOTE Requests

The syntax of a promotion check message is similar to that of the PACKAGE SERVICE PROMOTE request, with the following exceptions:

  • the name attribute in the <scope> tag has a value of “CHECK"

  • the <applName>, <packageId>, <scheduledate>, and <scheduletime> tags are not used

A code example appears in this chapter under Promote a Package - PACKAGE SERVICE PROMOTE. Data structure details for the promotion check <request> tag are discussed in Exhibit 4-8.

PACKAGE CHECK PROMOTE Replies

No <result> data structure is returned in the reply message to a promotion check request. However, the standard <response> data structure is returned to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Promote a Package - PACKAGE SERVICE PROMOTE

Package promotion applies the changes in a package to libraries used for testing and other purposes. All components to be promoted must be active, and business rules for promotion level transitions, promotion to remote sites, and package freeze must also be met.

The Serena XML service/scope/message tags for a package promotion message are:

<service name="PACKAGE"> 
<scope name="SERVICE">
<message name="PROMOTE">

These tags appear in both requests and replies.

The package promote function validates the promotion readiness of a package prior to executing the promote. It necessarily file-tailors the package for application to the target promotion library, as well — a step that can take some time.

Tip

To check the promotion readiness of a package in Serena XML without file tailoring for promotion or actually executing the promote, use package/check/ promote. (See Check a Package for Promotion Readiness - PACKAGE CHECK PROMOTE.)

PACKAGE SERVICE PROMOTE Request

Serena XML supports all three types of promotion: full promote, selective promote, and “first" promote. No special XML attribute or tag is required to choose a promotion type. ChangeMan ZMF determines the appropriate promotion type based on whether or not you supply an explicit component name (which indicates a selective promote), and on the business rules defined for promotion by your administrator (which may or may not allow a “first" promote).

The example below shows how you might code a selective promotion request in Serena XML. Data structure details for the packageservice promote <request> tag appear in Exhibit 4-8.

Example XML — PACKAGE SERVICE PROMOTE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="PROMOTE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000012</package>
                <promotionSiteName>SERT8</promotionSiteName>
                <promotionLevel>10</promotionLevel>
                <promotionName>C001AUT</promotionName>
                <jobCards01>//XMLX130 JOB (AMW,000),'DEFINE UCAT',MSGCLASS=Y,</jobCards01>
                <jobCards02>// TIME=(,10),NOTIFY=USER24</jobCards02>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-8. PACKAGE SERVICE PROMOTE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<component> Optional 0 - 800 Complex See Exhibit 4-9.
NOTE: Required for selective promote. If used, <listCount> tag is also required.
<jobCards01> Required 1 String (72), fixed length First of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards02> Optional 0 - 1 String (72), fixed length Second of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards03> Optional 0 - 1 String (72), fixed length Third of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards04> Optional 0 - 1 String (72), fixed length Fourth of up to 4 JCL statements needed to execute the promote in batch mode.
<listCount> Optional 0 - 1 Integer (3), variable Number of components to selectively promote. Must match number of <component> tags. Value range: 1 - 800
NOTE: Required for selective promote. If used, <component> tag is also required.
<overlayTargetComponents> Optional 0 - 1 String (1) Option to automatically overlay package components already in target library. Values: Y = Yes, overlay components N = No, don’t overlay
<package> Required 1 String (10), fixed Fixed-format ZMF package
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<promotionLevel> Required 1 Integer (2), variable Sequence number of target promotion library in promotion hierarchy.
<promotionName> Required 1 String (8), variable Promotion/demotion nickname.
<promotionSiteName> Required 1 String (8), variable Name of site where target promotion library resides.
<scheduledate> Optional 0 - 1 String (8) A date with no time (yyyyMMdd)
<scheduletime> Optional 0 - 1 String (4) A time (HHmm)
<suppressNotify> Optional 0 - 1 String (1) Y = Yes, suppress notify
N = No, don’t suppress
<userVariable01> . . . <userVariable05> Optional 0 - 1 each String (8), variable Up to five user-defined variables of 8 bytes each, used to pass parameters to JCL interpreter.
<userVariable06> . . . <userVariable10> Optional 0 - 1 each String (72), variable Up to five user-defined variables of 72 bytes each, used to pass parameters to JCL interpreter.

...

Tip

Tags: <userVariable01> to <userVariable10>: See topic “Custom V01-V10 Variables" in the ChangeMan ZMF Customization Guide.

<component> Subtag

In a selective or a “first" package promotion request, you explicitly name each component to promote. The <component> subtag serves this purpose. It delimits a complex data structure containing the name and library type of each component to be promoted, and is repeatable as many times as needed to accommodate the components selected for promotion.

This <component> tag does not stand alone. When used, it requires a <listCount> tag to precede the first instance of the <component> tag in the message. The <listCount> tag contains a count of components to be promoted. That number must match the actual number of <component> tags that immediately follow.

Data structure details for the complex <component> subtag appear in Exhibit 4-9

Exhibit 4-9. <component> Subtag Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<componentName> Required 1 String (256), variable If PDS member, the member name (max 8 bytes, no qualifiers). If HFS file, the Unix-style long file name, optionally prefixed by path from installation root.
<componentType> Required 1 String (3), fixed Library type of component in <componentName>.

Package Service Promote Reply

No <result> data structure is returned in package promotion reply message. However, the standard <response> data structure is returned to indicate the success or failure of the promotion request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Lock Promotion Site for Package - PACKAGE PROMOTE LOCK

The Package Promote Lock service locks the promotion site for a requested package.

The Serena XML service/scope/message tags for a promotion site lock message are:

<service name="PACKAGE">
<scope name="PROMOTE">
<message name="LOCK">

These tags appear in both requests and replies.

PACKAGE PROMOTE LOCK Request

The example below shows how you might code a Package Promote Lock request in Serena XML. Data structure details for the <request> tag appear in Exhibit 4-10.

Example XML — PACKAGE PROMOTE LOCK Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="PROMOTE">
        <message name="LOCK">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000012</package>
                <promotionSiteName>SERT8</promotionSiteName>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-10. PACKAGE PROMOTE LOCK <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<promotionSiteName> Required 1 String (8), variable Name of site where target promotion library resides.

Package Promote Lock Reply

No <result> data structure is returned in a Package Promote Lock reply message. However, the standard <response> data structure is returned to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Demote a Package - PACKAGE SERVICE DEMOTE

The standard package demotion function resets the desired components previously promoted to a specific promotion site and level to promotion level 00 in the staging library. In a full demote, it also resets the package master to development status. Copies of previously promoted components are deleted.

The Serena XML service/scope/message tags for a message to demote a package:

<service name="PACKAGE">
<scope name="SERVICE">
<message name="DEMOTE">

These tags appear in both requests and replies.

PACKAGE SERVICE DEMOTE Request

Serena XML supports both full demotion and selective demotion. No special XML attribute or tag is required to choose a demotion type. ChangeMan ZMF determines the appropriate demotion type based on whether or not you supply an explicit component name (which indicates a selective demote).

Except for the name attribute in the <scope> tag, the syntax of a request to demote a package is identical to that of a promotion request. A code example appears in this chapter under Promote a Package - PACKAGE SERVICE PROMOTE. Data structure details for the promotion check <request> tag are discussed in Exhibit 4-8 also in Promote a Package - PACKAGE SERVICE PROMOTE.

PACKAGE SERVICE DEMOTE Reply

Serena XML reply messages for a package demotion request do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the demotion request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Demote a Package with Cleanup - PACKAGE CLEANUP DEMOTE

The package cleanup demote function performs a full package demotion for all package components previously promoted to any promotion level at a named site. The promotion libraries that were last promoted to are cleaned up. It then resets the package master to development status.

The Serena XML service/scope/message tags for a message to demote a package with cleanup are:

<service name="PACKAGE">
<scope name="CLEANUP">
<message name="DEMOTE">

These tags appear in both requests and replies.

PACKAGE CLEANUP DEMOTE Requests

The example below shows how you might code a request for demotion with cleanup in Serena XML. Data structure details for the <request> tag appear in Exhibit 4-11.

Example XML — PACKAGE CLEANUP DEMOTE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="CLEANUP">
        <message name="DEMOTE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000004</package>
                <promotionSiteName>SERT8</promotionSiteName>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-11. PACKAGE CLEANUP DEMOTE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<promotionSiteName> Required 1 String (8), variable Name of site where promotion library resides.
<suppressNotify> Optional 0 - 1 String (1), Suppress batch messages,Y or N.
<userVariable01> . . . <userVariable05> Optional 0 - 1 each String (8), variable Up to five user-defined variables of 8 bytes each, used to pass parameters to JCL interpreter.
<userVariable06> . . . <userVariable10> Optional 0 - 1 each String (72), variable Up to five user-defined variables of 72 bytes each, used to pass parameters to JCL interpreter.

Tip

Tags: <userVariable01> to <userVariable10>: See topic “Custom V01-V10 Variables" in the ChangeMan ZMF Customization Guide.

PACKAGE CLEANUP DEMOTE Replies

Serena XML reply messages for a package demotion with cleanup do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the demotion request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Example XML — PACKAGE CLEANUP DEMOTE Reply

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="CLEANUP">
        <message name="DEMOTE">
            <response>
                <statusMessage>CMN3261I - request submitted for demotion from SERT8,C001AUT.</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>3261</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

A successful PACKAGE CLEANUP DEMOTE request will generate a JOB with output similar to the following:

-STEPNAME PROCSTEP       RC     EXCP     CONN      TCB      SRB
-DEL1CPY                 00      37       18       .00      .00
-SUCCESS                 00     572      303       .00      .00
-CHKCOND                 00      15        6       .00      .00
-FAILURE              FLUSH       0        0       .00      .00
-PRINT                   00      64       24       .00      .00
-CLNLCL                  00      30       64       .00      .00
-SERT8      ENDED.    NAME-ACTP                       TOTAL TCB
$HASP395   SERT8      ENDED

DELETE ACPCPY00
ACPCPY00 WAS DELETED FROM TARGET DATA SET

*****************************************************************
* DDNAME: SUCCESS.SYSPRINT
*****************************************************************

ChangeMan(R)         CMNBATCH - 6.1.0     2009/02/17     11:55:22
ATTEMPTING TO INITIATE DIALOG WITH CHANGE MAN SUBTASK
SESSION ESTABLISHED WITH CHANGE MAN SUBTASK
SYSIN: TES5000004 85 FUN=DEMOTE,NOD=SERT8
SYSIN: TES5000004 85 LVL=10,LNM=C001AUT,CID=USER24
SYSIN: TES5000004 85 SUP=YES,SSI=5C6A9D1F
SYSIN: TES5000004 85 TYP=CPY
SYSIN: TES5000004 85 CMP=ACPCPY00 Component History has been updated.
Component Promotion History has been updated
Demotion logged TES5000004
SYSIN: TES5000004 85 FUN=END
Package Promotion history has been updated
Package TES5000004       DEMOTE 
Package General record has been updated.
END OF DATA ON SYSIN - TERMINATING
SESSION TERMINATED WITH CHANGE MAN STARTED TASK

<SIZE: RECS=25 BYTES=967>

...

Approve a Package - PACKAGE SERVICE APPROVE

The package approval function logs package approval actions such “approve" and “reject" and issues appropriate notifications. Approval entities may also override their previously defined notification addresses (e.g., to substitute a TCP/IP email address for a TSO “Send" message). Authorized approvers must be defined by approver list maintenance before they can approve a package.

Note

Approver list maintenance is a function of the approver maintenance service, not the package management service. This task is normally performed via ISPF.

The Serena XML service/scope/message tags for a package approval message are:

<service name="PACKAGE"> 
<scope name="SERVICE">
<message name="APPROVE">

These tags appear in both requests and replies.

PACKAGE SERVICE APPROVE Requests

The following example shows how you might code a package approval request using Serena XML. Data structure details for the package approval <request> tag appear in Exhibit 4-12.

Example XML — PACKAGE SERVICE APPROVE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="APPROVE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <approverAction>1</approverAction>
                <package>ACTP000009</package>
                <approverEntity>ACTPLEAD</approverEntity>
                <reasons>PACKAGE SERVICE APPROVE TEST</reasons>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-12. PACKAGE SERVICE APPROVE <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<approverAction> Required 1 Integer (1), fixed = Approve package = Checkoff = Approval decision pending = Reject package = Under review = Final approval for linked packages
NOTE: If value is 2 or 4, <reasons> tag required.
<approverEntity> Required 1 String (8), variable Security system entity ID of authorized application approver.
<notifierAgentIpAddress> Optional 0 - 1 String (32), variable Network IP address for E-mail notifications. Overrides user record.
NOTE: If used, also requires <notifierAgentPortid> tag.
<notifierAgentPortid> Optional 0 - 1 Integer (5), variable Network port ID of E-mail server for notifications. Overrides user record.
NOTE: Required with tag <notifierAgentIpAddress>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<reasons> Optional 0 - 14 String (72), variable Reject (or checkoff) reasons. May be repeated for multiple comments.
NOTE: If <approverAction> value = 2 or 4, this tag is required.

PACKAGE SERVICE APPROVE Replies

Serena XML reply messages to a package approval request do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the approval action. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

List Package Installation Schedule - SCHEDULE SERVICE LIST

This function lists installation scheduler records defined for a named package. Information returned includes planned installation dates, install job status if held or released, install job participation in a multi-package release, temporary change duration, and package backout status. If no installation information has been defined, no results are returned.

The Serena XML service/scope/message tags and attributes for messages that list installation schedule information for a package are:

<service name="SCHEDULE">
<scope name="SERVICE">
<message name="LIST">

These tags appear in both requests and replies.

SCHEDULE SERVICE LIST — Requests

Request messages for this function require only a package name. A date range may also be supplied.

Example XML — SCHEDULE SERVICE LIST Request

<?xml version="1.0"?>
<service name="SCHEDULE">
    <scope name="SERVICE">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000009</package>
            </request>
        </message>
    </scope> 
</service>

...

Data structure details for the <request> tag appear in Exhibit 4-13.

Exhibit 4-13. SCHEDULE SERVICE LIST<request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of <package>.
NOTE: Not recommended. Use <package> instead of separately specifying <applName> and <packageId>.
NOTE: OK to omit trailing blanks.
<backoutJobSubmitted> Optional 1 String (1) Y = Yes, backout job submitted
N = Backout job not submitted
<installDate> Optional 0 - 1 Date, yyyymmdd Planned install date for package, or start date of range.
<installJobHeld> Optional 1 String (1) Y = Yes, install job held
N = No, install job not held
<installJobSubmitted> Optional 1 String (1) Y = Yes, install job submitted
N = No, install job not submitted
<isReasonsInserted> Optional 1 String (1) Y = Yes, reason codes present
N = No, reason codes absent
<package> Required 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID. Same as last 6 bytes of <package>.
NOTE: Not recommended. Use <package> instead of separately specifying <applName> and <packageId>.
NOTE: Leading zeroes required.
<releaseInstallation> Optional 1 String (1) Y = Yes, install with release
N = No, not a release install
<toInstallDate> Optional 0 - 1 Date, yyyymmdd End date of planned installed date range.
<type> Optional 0 - 1 1 Type of job scheduled, I = Install, P = Promote

SCHEDULE SERVICE LIST — Replies

The Serena XML reply message for this function returns one <result> tag, which contains installation scheduler information for a named package. It is followed by the standard <response> data element, which indicates the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Example XML — SCHEDULE SERVICE LIST Reply

<?xml version="1.0"?>
<service name="SCHEDULE">
    <scope name="SERVICE">
        <message name="LIST">
            <result>
                <package>ACTP000009</package>
                <applName>ACTP</applName>
                <packageId>000009</packageId>
                <type>I</type>
                <installDate>20091231</installDate>
                <installTime>0100</installTime>
                <installJobSubmitted>Y</installJobSubmitted>
                <installJobHeld>Y</installJobHeld>
                <isReasonsInserted>Y</isReasonsInserted>
                <backoutJobSubmitted>Y</backoutJobSubmitted>
                <releaseInstallation>Y</releaseInstallation>
                <tempChangeDuration>000</tempChangeDuration>
                <updateToken>5C7529CB</updateToken>
            </result>
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>  
</service>

...

Data structure details for the <result> tag appear in Exhibit 4-14.

Exhibit 4-14. SCHEDULE SERVICE LIST <result> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of <package>.
<backoutJobSubmitted> Optional 1 String (1) Y = Yes, backout job submitted
N = Backout job not submitted
<installDate> Optional 0 - 1 Date, yyyymmdd Planned installation date, or first date in range of install dates.
<installJobHeld> Optional 1 String (1) Y = Yes, install job held
N = No, install job not held
<installJobSubmitted> Optional 1 String (1) Y = Yes, install job submitted
N = No, install job not submitted
<installTime> Optional 0 - 1 Time, hhmmss Planned install time in 24-hour format.
<isReasonsInserted> Optional 1 String (1) Y = Yes, reason codes present
N = No, reason codes absent
<package> Optional 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID. Same as last 6 bytes of <package>.
<reasonCode> Optional 0 - 1 String (3), variable Reject reason code if package rejected or backed out.
<releaseInstallation> Optional 1 String (1) Y = Yes, install with release
N = No, not a release install
<tempChangeDuration> Optional 0 - 1 String (3), variable Life of temporary change package before automatic backout.
<type> Optional 0 - 1 1 Type of job scheduled,
I = Install, P = Promote
<updateToken> Optional 0 - 1 String (8), variable Binary hash token for updated package.

...

Hold Package Install Job - SCHEDULE SERVICE HOLD

This function holds a package installation job in the scheduling queue until it is explicitly released. The Serena XML service/scope/message tags and attributes for messages to hold a package install job are:

<service name="SCHEDULE">
<scope name="SERVICE">
<message name="HOLD">

These tags appear in both requests and replies.

SCHEDULE SERVICE HOLD — Requests

The request message for this function requires a package name. No filtering options are supported. Data structure details for the <request> tag appear in Exhibit 4-15.

Exhibit 4-15. SCHEDULE SERVICE HOLD <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of <package>.
NOTE: Not recommended. Use <package> instead of separately specifying <applName> and <packageId>.
NOTE: OK to omit trailing blanks.
<package> Required 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID. Same as last 6 bytes of <package>.
NOTE: Not recommended. Use <package> instead of separately specifying <applName> and <packageId>.
NOTE: Leading zeroes required.
<type> Optional 0 - 1 1 Type of job scheduled, I = Install, P = Promote

SCHEDULE SERVICE HOLD — Replies

No <result> tag is returned in the Serena XML reply message for a package install job hold request. However, the reply message does return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Release Package Install Job - SCHEDULE SERVICE RELEASE

This function releases a previously held package installation job in the scheduling queue. The Serena XML service/scope/message tags and attributes for messages to release a package install job are:

<service name="SCHEDULE">
<scope name="SERVICE">
<message name="RELEASE">

These tags appear in both requests and replies.

SCHEDULE SERVICE RELEASE — Requests

The request message syntax to release a package install job is different from that to hold an install job only in the name attribute of the <message> tag, as shown above. Data structure details for the <request> tag are identical in both messages. They appeared previously in Exhibit 4-15.

SCHEDULE SERVICE RELEASE — Replies

No <result> tags are returned in the Serena XML reply message for a package install job release request. However, the reply message does return a standard <response> data element to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Back Out a Package - PACKAGE SERVICE BACKOUT

The package service backout function reverses a package baseline ripple. Serena XML does not back out changes to production libraries.

Note

If a package resides in remote production libraries as well as the baseline library, you must back out each installed instance of the package from the production libraries via the ISPF interface before you issue a Serena XML backout request.

The Serena XML service/scope/message tags for a package backout message are:

<service name="PACKAGE"> 
<scope name="SERVICE">
<message name="BACKOUT">

These tags appear in both requests and replies.

PACKAGE SERVICE BACKOUT Requests

Serena XML allows you to back out a package with or without validating the integrity of your baseline libraries afterward. This flexibility saves time when backing out minor or temporary changes. However, unless you are completely certain that the changes to be backed out are minor, you should validate baseline integrity as part of the backout process.

An example of how you might code a Serena XML request to back out a package from baseline appears below. Data structure details for the package backout <request> tag appear in Exhibit 4-16.

Example XML — PACKAGE SERVICE BACKOUT Request

<?xml version="1.0" encoding="UTF-8"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="BACKOUT">
            <header>
                <subsys>8</subsys>
                <product>CMN</product> 
            </header>
            <request>
                <package>ACTP000012</package>
                <siteName>SERT8</siteName>
                <backoutReason01>TEST XML PACKAGE SERVICE BACKOUT</backoutReason01>
                <jobCards01>//XMLX127 JOB (AMW,000),'DEFINE UCAT',MSGCLASS=Y,</jobCards01>
                <jobCards02>// TIME=(,10),NOTIFY=USER24</jobCards02>
            </request>
        </message>  
    </scope> 
</service>

...

Exhibit 4-16. PACKAGE SERVICE BACKOUT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
backoutReason01 Optional 0 - 1 String (72), variable Backout reasons line - 1
backoutReason02 Optional 0 - 1 String (72), variable Backout reasons line - 2
backoutReason03 Optional 0 - 1 String (72), variable Backout reasons line - 3
backoutReason04 Optional 0 - 1 String (72), variable Backout reasons line - 4
backoutReason05 Optional 0 - 1 String (72), variable Backout reasons line - 5
backoutReason06 Optional 0 - 1 String (72), variable Backout reasons line - 6
backoutReason07 Optional 0 - 1 String (72), variable Backout reasons line - 7
backoutReason08 Optional 0 - 1 String (72), variable Backout reasons line - 8
backoutReason09 Optional 0 - 1 String (72), variable Backout reasons line - 9
<jobCards01> Optional 0 - 1 String (72), fixed length First of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards02> Optional 0 - 1 String (72), fixed length Second of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards03> Optional 0 - 1 String (72), fixed length Third of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards04> Optional 0 - 1 String (72), fixed length Fourth of up to 4 JCL statements needed to execute the promote in batch mode.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<siteName> Optional 1 String (8), variable Name of site where target demotion library resides.
<validateBackout> Optional 0 - 1 String (1) Y = Yes, validatebackout only. N** = No, perform backout.

...

PACKAGE SERVICE BACKOUT Replies

The Serena XML reply messages to a package backout request do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the revert request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

Successful requests will send messages like the following to the user who initiated the backout:

CMN406I - ACTP000012 BACKED OUT 2009/02/18 @ 08:36:08 AT SERT8, CN(INTERNAL) 
CMN410I - ACTP000012 BASELINE REVERSE RIPPLED 2009/02/18 @ 08:36:08. CN(INTERNAL)

Successful requests will submit a BACKOUT JOB with output similar to the following:

-STEPNAME PROCSTEP       RC     EXCP     CONN      TCB      
-CMN00                   00      554      301      .00
-RESTCPY                 00      133      245      .00
-DSPTM                   00      611      323      .00
-RRIPPIA              FLUSH        0        0      .00
-CMN00                   00      552      299      .00
-CMN99                   00       14        5      .00
-FAILURE              FLUSH        0        0      .00
-PRINT                   00       33       16      .00
-ACTP5512 ENDED.   NAME-ACTP T
$HASP395 ACTP5512  ENDED
//* IMS OPTION: JOB TO PERFORM REVERSE RIPPLE OF PACKAGE ACTP000012
ChangeMan(R) CMNBATCH - 6.1.0 2009/02/18 08:36:08
ATTEMPTING TO INITIATE DIALOG WITH CHANGE MAN SUBTASK
SESSION ESTABLISHED WITH CHANGE MAN SUBTASK
SYSIN: ACTP000012 55 NOD=SERT8
PACKAGE BACKED OUT AT DEV.                           ACTP000012
BACKOUT AT DEV LOGGED.                               ACTP000012
BASELINE REVERSE RIPPLE LOGGED                       ACTP000012
END OF DATA ON SYSIN - TERMINATING
SESSION TERMINATED WITH CHANGE MAN STARTED TASK

Revert a Package - PACKAGE SERVICE REVERT

The package revert function reverts a package to development status after it has been backed out from baseline.

The Serena XML service/scope/message names for a package revert message are:

<service name="PACKAGE">
<scope name="SERVICE">
<message name="REVERT">

These tags appear in both requests and replies.

PACKAGE SERVICE REVERT Requests

You have the option to revert a package with or without concurrent validation of the staging library. However, validation is recommended.

Tip

To validate the staging library as part of your package revert request, enter “2” in the <validationParm> tag.

The following example shows how you might code a package revert request using Serena XML. Data structure details for the package revert <request> tag appear in Exhibit 4-17.

Example XML — PACKAGE SERVICE REVERT Request

<?xml version="1.0" encoding="UTF-8"?>
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="REVERT">
            <header>
                <subsys>8</subsys>
                <product>CMN</product> 
            </header>
            <request>
                <package>ACTP000012</package>
                <siteName>SERT8</siteName>
                <backoutReason01>TEST XML PACKAGE SERVICE REVERT</backoutReason01>
                <jobCards01>//XMLX134 JOB (AMW,000),'DEFINE UCAT',MSGCLASS=Y,</jobCards01>
                <jobCards02>// TIME=(,10),NOTIFY=USER24</jobCards02>
            </request>
        </message>  
    </scope> 
</service>

...

Exhibit 4-17. PACKAGE SERVICE REVERT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<jobCards01> Optional 0 - 1 String (72), fixed length First of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards02> Optional 0 - 1 String (72), fixed length Second of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards03> Optional 0 - 1 String (72), fixed length Third of up to 4 JCL statements needed to execute the promote in batch mode.
<jobCards04> Optional 0 - 1 String (72), fixed length Fourth of up to 4 JCL statements needed to execute the promote in batch mode.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<revertReason01> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason02> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason03> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason04> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason05> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason06> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason07> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason08> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<revertReason09> Optional 1 String (72), variable Free format text of reason for reverting package to development.
<siteName> Required 1 String (8), variable Name of site where target revert library resides.
<validationParm> Optional 0 - 1 Integer (1) 2** = Determine whether package is eligible for revert. Revert is not actually performed.

...

PACKAGE SERVICE REVERT Replies

Serena XML replies to a package revert request do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the revert request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.