Skip to content

Package-level Component Change Management

Package-level component change tasks apply to one or more components within a particular change package. For example, you can work with the source and load components in a package, the non-source components (such as copybooks) in a package, or scratch/rename records in a package. Typical operations on components at the package level are list, unfreeze and refreeze.

Package-level component change management tasks include:
• *Component Change Description List - CMPONENT CHG_DESC LIST • *Unfreeze Non-Source Components - PACKAGE NON_SRC UNFREEZE
• *List Staged Components - CMPONENT PKG_COMP LIST • *Refreeze Non-Source Components - PACKAGE NON_SRC REFREEZE
• *Component Description List- PACKAGE CMP_DESC LIST • *List Scratch and Rename Utility Records -CMPONENT PKG_UTIL LIST
• *List Components With Promotion Overlays - PACKAGE PRM_OVLY LIST AGE SCR_REN UNFREEZE • *Unfreeze Scratch/Rename Records - PACKAGE SCR_REN REFREEZE
• *Unfreeze Source/Load Components - PACKAGE SRC_LOD UNFREEZE • *Refreeze Scratch/Rename Records - PACKAGE SCR_REN REFREEZE
• *Refreeze Source/Load Components - PACKAGE SRC_LOD REFREEZE

Component Change Description List- CMPONENT CHG_DESC LIST

List all or any components in a package, together with their package-specific change descriptions, using the Serena XML component change description list function. All component types are included in the scope of this function, including source code members, load members, copybooks, skeletons, ISPF panels, and JCL procedures.

The Serena XML service/scope/message names for a component change description list at the package level are:

<service name="CMPONENT">
<scope name="CHG_DESC"> 
<message name="LIST">

These tags appear in both requests and replies.

CMPONENT CHG_DESC LIST — Request

Three common uses for component change description lists in Serena XML are:

  • List All Components in Package — Name the desired package in the <package> tag. Enter a “match-all" (asterisk) wildcard character in both the <component> and <componentType> tags, or omit these tags altogether. All components in the package will be returned, together with their package-level change descriptions.

  • List All Components of Given Library Type — Name the desired package in the <package> tag and the desired library type in the <componentType> tag. Enter a “match-all" (asterisk) wildcard character in the <component> tag or omit it altogether. All package components of the desired library type will be returned, together with their change descriptions, if a change description exists.

  • Get Package-Level Change Description for Named Component — Name the desired package in the <package> tag and the desired component name in the <component> tag. Enter the library type of the component in the <componentType> tag if known; otherwise, enter a “match-all" (asterisk) wildcard character. The desired component and its change description are returned if the component exists in the package.

The following example shows how you might code a request to list all components for package ACTP000001 and any existing change descriptions using Serena XML. Data structure details follow the example in Exhibit 4-18.

Example XML — CMPONENT CHG_DESC LIST Reque

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="CHG_DESC">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000007</package>
            </request>
        </message>
    </scope>
</service>

Exhibit 4-18. CMPONENT CHG_DESC LIST <request>

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 - 1 String (256), variable ZMF name of desired component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root. Wildcards & patterns with question mark (?) & asterisk (*) are allowed.
<componentType> Optional 0 - 1 String (3), variable Library type for component. Wildcards & patterns with question mark (?) & asterisk (*) are allowed.
<package> Required 1 String (10), variable 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>.

CMPONENT CHG_DESC LIST — Reply

The XML reply to a component change description list request includes zero to many <result> tags. Each <result> tag contains the name, library type, and change description of a component in the named package if a change description exists.

A standard <response> tag follows the last <result> tag 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. As the last tag returned in the reply message, the <response> tag also serves as an end-of-list marker.

An example XML reply to a component change description list request appears on the next page. Data structure details for the <result> tag follow the example in Exhibit 4-19.

Example XML — CMPONENT CHG_DESC LIST Rep

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="CHG_DESC">
        <message name="LIST">
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY00</component>
                <componentType>CPY</componentType>
                <changeDesc>SER5904E</changeDesc>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1A</component>
                <componentType>CPY</componentType>
                <changeDesc>SER5904E</changeDesc>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1B</component>
                <componentType>CPY</componentType>
                <changeDesc>SER5904E</changeDesc>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1C</component>
                <componentType>CPY</componentType>
                <changeDesc>SER5904E</changeDesc>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1X</component>
                <componentType>CPY</componentType>
                <changeDesc>SER5904E</changeDesc> 
            </result> 
            .
            .
            .
            .
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

Exhibit 4-19. CMPONENT CHG_DESC LIST <result>

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of package name.
<changeDesc> Optional 0 - 1 String (35), variable Description of changes in progress with component in this package.
<component> Optional 0 - 1 String (256), variable ZMF name of component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentType> Optional 0 - 1 String (3), variable Library type for component.
<package> Optional 0 - 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.

List Staged Components - CMPONENT PKG_COMP LIST

List staged components for a package using the Serena XML function to list staged “sourceand-load" (ISAL and ICPY) components. These include “like-source", “like-load", “likecopybook", and “like-PDS" components staged from baseline or staged from development.

The Serena XML service/scope/message names for a staged component list at the package level are:

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

These tags appear in both requests and replies.

CMPONENT PKG_COMP LIST — Request

The primary uses for a request to list staged components are:

  • List All Staged Components in a Package — Name the desired package in the <package> tag. Submit a blank in <recordType> or omit this tag altogether. Component name, library type, and status are returned for each staged component in the named package.

  • List Staged Source and Load Components — Name the desired package in the <package> tag. Enter an “A" in the <recordType> tag to request staged source-andload (ISAL) records. For each staged “like-source" and “like-load" component in the package, this function returns the component name, library type, and status. If a staged like-source component has been compiled while staged, its record will also include a pointer to the primary “like-load" component generated by the compile. “Like-copybook" and “like-PDS" components are not listed.

  • List Other Staged Components — Name the desired package in the <package> tag. Enter a “6" in the <recordType> tag to request staged copy-and-include (ICPY) records. The function lists component name, library type, and status information for all staged “like-copybook" and “like-PDS" components in the named package, including copybooks, skeletons, JCL procedures, and ISPF panels. Like-source and like-load components are not listed.

  • Verify That a Particular Component Was Staged — Supply the desired component name in <component>, the component library type in <componentType>, and the package name in <package>. Submit a blank in <recordType> or omit this tag altogether. If the component was staged to the package named, a <result> data structure will return information about the desired component. If the component was not staged to that package, no results will be returned.

To further customize your query for a staged component list request, specify a library type, modification date range, updater ID, or component status of interest. Choose component status options using appropriate yes/no flag tags.

Note

Yes/no flags for component status filtering take default values as a group. The default changes based on whether or not you enter explicit values in these tags, as follows:

  • If no status flag has an explicitly typed value, the default for all tags is “Y".

  • If any status flag has an explicitly typed value, the default for the remaining tags is “N".

Build-Option Reply Tags

The following build-option reply tags are not automatically retrieved:

<compileOptions>
<linkOptions>
<useDb2PreCompileOption>
<userOption01> thru <userOption20>
<userOption0101> thru <userOption0105>
<userOption0201> thru <userOption0203>
<userOption0301> thru <userOption0303>
<userOption0401> thru <userOption0403>
<userOption0801> thru <userOption0805>
<userOption1001> thru <userOption1002>
<userOption1601> thru <userOption1602>
<userOption3401> thru <userOption3402>
<userOption4401> thru <userOption4402>
<userOption6401> thru <userOption6405>
<userOption7201> thru <userOption7205>

Displaying these tags causes an increase in run time because the data must be retrieved from the component history records. Therefore, these tags are not retrieved unless you request them using the following tag:

<longFormat>Y</longFormat>

The default is “N" (do not retrieve the build-option tags).

The following example shows how you might code a request to list all source and load components staged to a package. Data structure details for the <request> tag appear in Exhibit 4-20.

Example XML — CMPONENT PKG_COMP LIST

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="PKG_COMP">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>CISQ000030</package>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-20. CMPONENT PKG_COMP LIST <request>

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 1 String (256), variable ZMF name of staged component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root. Asterisk (*) wildcard is allowed.
<componentType> Optional 0 -1 String (3), variable Library type of staged component.
NOTE: Takes asterisk (*) wildcard.
<filterActiveStatus> Optional 0 - 1 String (1) Y = Include active components
N = Omit active components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterCheckedOutStatus> Optional 0 - 1 String (1) Y = Include checked-out components
N = Omit checked-out components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterFrozenStatus> Optional 0 - 1 String (1) Y = Include frozen components
N = Omit frozen components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterHfsDirectory> Optional 0 - 1 String (256), variable Name of HFS directory containing components to be listed, prefixed by path from installation root (that is, path as stored in baseline library). If present, only files in this directory are listed. If absent, all HFS files meeting other criteria are listed.
NOTE: Applies to z/OS Unix HFS components only. Irrelevant for native z/OS PDS library members.
<filterInactiveStatus> Optional 0 - 1 String (1) Y = Include inactive components
N = Omit inactive components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterIncompleteStatus> Optional 0 - 1 String (1) Y = Include incomplete components
N = Omit incomplete components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterUnfrozenStatus> Optional 0 - 1 String (1) Y = Include unfrozen components
N = Omit unfrozen components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<fromDateLastModified> Optional 0 -1 Date, yyyymmdd Start date in desired range of staged component modification dates.
<lockId> Optional 0-1 String (7) UserID component locked by (if locked)
<longFormat> Optional 0 - 1 String (1) Tag for requesting the build-option tags from component history data. The default is N. Y = Retrieve build-option tags
N = Do not retrieve build-option tags
<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>.
<recordType> Optional 0 - 1 String (1) Type of staged component record to list. Values:
A = ISAL (like-source & like-load)
6 = ICPY (like-copybook, like-PDS)
Blank = Both record types
NOTE: Omit tag or enter explicit blank to list both record types. Null tag returns no records.
NOTE: Asterisk (*) wildcard not accepted in this tag.
<targetComponent> Optional 0 - 1 String (256), variable Name of a component, target member name. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<toDateLastModified> Optional 0 -1 Date, yyyymmdd End date in desired range of staged component modification dates.
<updater> Optional 0 -1 String (8), variable TSO user ID of last person to update staged component.

CMPONENT PKG_COMP LIST Replies

The Serena XML reply to a staged component list request returns zero to many <result> data structures. Each <result> element lists one staged component, together with package name and component status information. If a staged, like-source component has been compiled after staging, the <result> also names its primary like-load target component.

In addition to any <result> data elements, the reply message returns a standard <response> data structure 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. Because the <response> tag follows the last <result> tag, it also serves as an end-of-list marker.

The example below shows how a reply for this function might appear in Serena XML. Data structure details for the <result> tag appear in Exhibit 4-21.

Example XML — CMPONENT PKG_COMP LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="PKG_COMP">
        <message name="LIST">
            <result> 
                <recordType>6</recordType>
                <package>CISQ000030</package>
                <applName>CISQ</applName>
                <packageId>000030</packageId>
                <component>CI2Q101</component>
                <targetComponent>CI2Q101</targetComponent>
                <componentType>LCT</componentType>
                <dateLastModified>20081126</dateLastModified>
                <timeLastModified>094237</timeLastModified>
                <updater>USER24</updater>
                <componentStatus>4</componentStatus>
                <sourceLibOrg>PDS</sourceLibOrg>
                <sourceLib>CMNTP.SERT8.BASE.CISQ.LCT</sourceLib>
                <chkOutLevel>00</chkOutLevel>
                <version>01</version>
                <modLevel>01</modLevel>
                <hashToken>C647B43A0000001B</hashToken>
                <baseDateLastModified>20080407</baseDateLastModified>
                <baseTimeLastModified>095500</baseTimeLastModified>
                <dataType>1</dataType>
                <chkOutToStageLib>N</chkOutToStageLib>
                <chkOutFromBaseLib>N</chkOutFromBaseLib>
                <chkOutToSernet>N</chkOutToSernet>
                <batchChkOut>N</batchChkOut>
                <chkOutComponentDesc>N</chkOutComponentDesc>
                <chkOutFromRelease>N</chkOutFromRelease>
                <lockComponent>Y</lockComponent>
                <checkedOutHashToken>0000000000000000</checkedOutHashToken>
                <lockId>USER015</lockId>
            </result>
            .
            .
            .
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

Exhibit 4-21. CMPONENT PKG_COMP LIST <result>

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.
<baseDateLastModified> Optional 0 -1 Date, yyyymmdd Date baseline version of staged component was last modified.
<baseSetssi> Optional 0 - 1 String (8), fixed Baseline component SETSSI date (seconds since 1/1/1960).
<baseTimeLastModified> Optional 0 -1 Time, hhmmss Time baseline version of staged component was last modified, 24 hr format.
<batchChkOut> Optional 0 - 1 String (1) Y = Batch checkout mode
N = Not batch checkout mode
<buildProc> Optional 0 - 1 String (8), variable Name of required build procedure used with staged component.
NOTE: Applies only to source code component in ISAL records.
<checkedOutHashToken> Optional 1 String (16), fixed Component hash at checkout.
<chkOutComponentDesc> Optional 0 - 1 String (1) Y = Description checked out
N = Description not checked out
<chkOutFromBaselib> Optional 0 - 1 String (1) Y = Checked out from baseline
N = Not checked out from baseline library
<chkOutFromRelease> Optional 1 String(1) Y = Checked out from release N = Not checked out from release
<chkOutLevel> Optional 0 - 1 Integer (2) Checkout level number for staged component.
<chkOutToSernet> Optional 0 - 1 String (1) Y = Checked out to SERNET
N = Not checked out to SERNET
<chkOutToStageLib> Optional 0 - 1 String (1) Y = Checked out to staging lib
N = Not checked out to staging
<compileOptions> Optional 0 - 1 String (34) Compile options for component not stored elsewhere.
NOTE: Displayed only if <longFormat> request tag = “Y".
<component> Optional 1 String (256), variable ZMF name of staged component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentStatus> Optional 0 -1 String (1) Code for staged component status. Values:
0 = Active
1 = Approved
2 = Checked Out
3 = Demoted
4 = Frozen
5 = Inactive
6 = Incomplete
7 = Promoted
8 = Refrozen
9 = Rejected
A = Remote Promoted
B = Submitted
C = Unfrozen
<componentType> Optional 0 - 1 String (3), fixed Library type of staged component.
<dataType> Optional 0 -1 String (1) File type of staged component for data transfers. Values:
1 = Text
2 = Binary
<dateLastModified> Optional 0 -1 Date, yyyymmdd Date staged component was last modified.
<encryption> Optional 0 -1 String (8) Staged component encryption key.
<hashtoken> Optional 0 - 1 String (16), fixed Hash token or “fingerprint" of staged component.
<language> Optional 0 - 1 String (8), variable Language name of component.
<linkOptions> Optional 0 - 1 String (34) Link options for component not stored elsewhere.
NOTE: Displayed only if <longFormat> request tag = “Y".
<lockComponent> Optional 0 - 1 String (1) Y = Component locked
N = Component not locked
<lockId> Optional 0-1 String (7) UserID component locked by (if locked)
<modLevel> Optional 0 -1 String (2), fixed ISPF modification level of staged component.
<package> Optional 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.
<recordType> Optional 1 String (1) Type of staged component record listed. Values:
A = ISAL (like-source & like-load)
6 = ICPY (like-copybook, like-PDS)
Blank = Both record types
<setssi> Optional 0 - 1 String (8), fixed Staged component SETSSI date (seconds since 1/1/1960).
<sourceLib> Optional 0 -1 String (44), variable Data set name of staged component library if PDS.
<sourceLibOrg> Optional 0 -1 String (3), fixed Data organization of staged component library. Values:
HFS = Hierarchical File System
Lib = Librarian
Pan = Panvalet
PDS = PDS or PDS/E
Seq = Sequential
Oth = Other
<targetComponent> Optional 0 - 1 String (256), variable ZMF name of primary like-load component generated from <component> while staged. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<targetLoadLibType> Optional 0 - 1 String (3), fixed Library type of component named in <targetComponent> (relink).
<timeLastModified> Optional 0 -1 Time, hhmmss Time staged component was last modified, 24 hr format.
<updater> Optional 0 -1 String (8), variable TSO user ID of last person to update staged component.
<useDb2PreCompileOption> Optional 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile for DB2
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption01> . . . <userOption20> Optional 0 - 1 String (1) Set of up to 20 one-byte, custom, administrator-defined variables. Values:
Y = Yes
N = No
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption0101> . . . <userOption0105> Optional 0 - 1 each String (1), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 0101 to 0105 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption0201> . . . <userOption0203> Optional 0 - 1 each String (2), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 0201 to 0203 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption0301> . . . <userOption0303> Optional 0 - 1 each String (3), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 0301 to 0303 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption0401> . . . <userOption0403> Optional 0 - 1 each String (4), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 0401 to 0403 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption0801> . . . <userOption0805> Optional 0 - 1 each String (8), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 0801 to 0805 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption1001> . . . <userOption1002> Optional 0 - 1 each String (10), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 1001 to 1002 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption1601> . . . <userOption1602> Optional 0 - 1 each String (16), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 1601 to 1603 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption3401> . . . <userOption3402> Optional 0 - 1 each String (34), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 3401 to 3402 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption4401> . . . <userOption4402> Optional 0 - 1 each String (44), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 4401 to 4402 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption6401> . . . <userOption6405> Optional 0 - 1 each String (64), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 6401 to 6405 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<userOption7201> . . . <userOption7205> Optional 0 - 1 each String (72), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 7201 to 7205 on the ISPF user options panel for component build.
NOTE: Displayed only if <longFormat> request tag = “Y".
<utilType> Optional 0 -1 String (1), fixed Utility type - ‘C’ recompile, ‘L’ relink.
<version> Optional 0 -1 String (2), fixed ISPF version number of staged component.

Component Description List- PACKAGE CMP_DESC LIST

List the component descriptions for specified components and types within a package using the Serena XML “package component description list" function. All component types are included in the scope of this function, including source code members, load members, copybooks, skeletons, ISPF panels, and JCL procedures.

The Serena XML service/scope/message names for a component description list at the package level are:

<service name="PACKAGE"> 
<scope name="CMP_DESC"> 
<message name="LIST">

These tags appear in both requests and replies.

PACKAGE CMP_DESC LIST — Request

Three common uses for package component description lists in Serena XML are:

  • List All Components in Package — Name the desired package in the <package> tag. Enter a “match-all" (asterisk) wildcard character in both the <component> and <componentType> tags. All components in the package that have a description will be returned.

  • List All Components of Given Library Type — Name the desired package in the <package> tag and the desired library type in the <componentType> tag. Enter a “match-all" (asterisk) wildcard character in the <component> tag. All package components of the desired library type will be returned, together with their descriptions, if a description exists.

  • Get Description for Named Component — Name the desired package in the <package> tag and the desired component name in the <component> tag. Enter the library type of the component in the <componentType> tag if known; otherwise, enter a “match-all" (asterisk) wildcard character. The desired component and its description are returned if the component exists in the package and it has a description.

The following example shows how you might code a request to list the description for a specific component in package ACTP000007. Data structure details follow the example in Exhibit 4-22.

Example XML — PACKAGE CMP_DESC LIST Request

<?xml version="1.0"?>
<service name="PACKAGE">
        <scope name="CMP_DESC">
            <message name="LIST">
                <header>
                    <subsys>8</subsys>
                    <product>CMN</product>
                </header>
                <request>
                    <package>ACTP000007</package>
                    <component>ACPSRC1A</component>
                    <componentType>SRC</componentType>
                </request>
            </message>
        </scope>
</service>

...

Exhibit 4-22. PACKAGE CMP_DESC LIST <request>

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> Required 1 String (256), variable ZMF name of desired component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root. Wildcards & patterns with question mark (?) & asterisk (*) are allowed.
<componentType> Required 1 String (3), variable Library type for component. Wildcards & patterns with question mark (?) & asterisk (*) are allowed.
<package> Required 1 String (10), variable 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>.

PACKAGE CMP_DESC LIST — Reply

The XML reply to a package component description list request includes zero to many <result> tags. Each <result> tag contains the name, library type, and description of a component in the named package if a description exists.

A standard <response> tag follows the last <result> tag 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. As the last tag returned in the reply message, the <response> tag also serves as an end-of-list marker.

An example XML reply appears on the next page. Data structure details for the <result> tag follow the example in Exhibit 4-23.

Example XML — PACKAGE CMP_DESC LIST Reply

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="CMP_DESC">
        <message name="LIST">
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY00</component>
                <componentDesc>ACCOUNT REC 00</componentDesc>
                <componentType>CPY</componentType>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1A</component>
                <componentDesc>ACCOUNT REC 1A</componentDesc>
                <componentType>CPY</componentType>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1B</component>
                <componentDesc>ACCOUNT REC 1B</componentDesc>
                <componentType>CPY</componentType>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <component>ACPCPY1C</component>
                <componentDesc>ACCOUNT REC 1C</componentDesc>
                <componentType>CPY</componentType>
            </result> 
            .
            .
            .
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage> 
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

Exhibit 4-23. PACKAGE CMP_DESC LIST <result>

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of package name.
<component> Optional 0 - 1 String (256), variable ZMF name of component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentDesc> Optional 0 - 48 String (72), variable Component description.
<componentType> Optional 0 - 1 String (3), variable Library type of component.
<package> Optional 0 - 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.

List Components With Promotion Overlays - PACKAGE PRM_OVLY LIST

If the promotion of a package would potentially cause some components to overwrite others of the same name — for example, as part of another package already in testing — you can know in advance using Serena XML. This function includes all component types and all promotion libraries for the package in its scope.

The Serena XML service/scope/message tags for a message to list package components with promotion overlays are:

<service name="PACKAGE"> 
<scope name="PRM_OVLY"> 
<message name="LIST">

These tags appear in both requests and replies.

PACKAGE PRM_OVLY LIST — Requests

Serena XML supports two kinds of component overlay lists:

  • All Components with Promotion Overlays — Name the desired package in the <package> tag and specify the promotion level of interest using the <promotionName>, <promotionLevel>, and <promotionSiteName> tags. Omit the <componentNameAndType> tag. The function returns promotion overlay information for all staged package components with duplicate component names and library types in the chosen promotion environment.

  • Promotion Overlays for Named Component(s) — Name the desired package in the <package> tag and specify the promotion level of interest using the <promotionName>, <promotionLevel>, and <promotionSiteName> tags. Itemize the components to check for promotion overlays using the <componentNameAndType> data element. A count of the itemized components is required in the <listcount> tag. The function returns overlay information only if an itemized component is duplicated in the target promotion environment.

The following example shows how you might code a request to check a particular package component for overlays in a named promotion library. Data structure details for the <request> tag appear in Exhibit 4-24.

Example XML — PACKAGE PRM_OVLY LIST Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="PRM_OVLY">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000002</package>
                <promotionSiteName>SERT8</promotionSiteName>
                <promotionLevel>10</promotionLevel>
                <promotionName>C001AUT</promotionName>
            </request>
        </message>
    </scope>  
</service>

...

Exhibit 4-24. PACKAGE PRM_OVLY 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 name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<componentNameAndType> Optional 0 - ∞ Complex Complex element identifies component(s) to check selectively. See Exhibit 4-25.
NOTE: If used, <listCount> required.
NOTE: Omit tag to list all components in package with promotion overlays.
<listCount> Optional 0 - 1 Integer (3), variable Count of <componentNameAndType> tags included in request.
NOTE: If <componentNameAndType> used, this tag is required.
<package> Required 1 String (10), variable 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>.
<promotionLevel> Required 1 Integer (2), variable Numeric code of promotion level to check for potential component overlays.
<promotionName> Required 1 String (8), variable ZMF name of promotion level to check for potential component overlays.
<promotionSiteName> Required 1 String (8), variable ZMF name of promotion site to check for potential component overlays.
<recallMigratedLib> Optional 0 - 1 String (1) Y = Yes, recall migrated shadow library
N = No, don’t recall shadow library

Note that <componentNameAndType> is a complex data element with subtags of its own. Its data structure appears in Exhibit 4-25.

Exhibit 4-25. <componentNameAndType> Data Structure

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

PACKAGE PRM_OVLY LIST — Replies

The Serena XML reply to a component overlay list request returns zero to many <result> data structures. Each <result> lists one component with potential component overlays in the named promotion library, together with package and component promotion status.

A package component has potential overlay issues in the target promotion library if:

  • A component with the same name and library type already exists in the target.

  • A component with the same name and library type exists in the promotion history records for the target.

If no duplicate components are found in either the target promotion library or its history records, no results are returned by this function.

In addition to any <result> tags, the reply message returns a standard <response> data structure 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. Because the <response> tag follows the last <result> tag, it also serves as an end-of-list marker.

The example below shows how a reply for this function might appear in Serena XML. Data structure details for the <result> tag appear in Exhibit 4-26.

Example XML — PACKAGE PRM_OVLY LIST Reply

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="PRM_OVLY">
        <message name="LIST">
            <result>
                <component>ACPSRS00</component>
                <componentType>SRS</componentType>
                <isComponentRestaged>N</isComponentRestaged> <overlayStatus>C</overlayStatus>
                <package>TES5000001</package>
                <applName>TES5</applName>
                <packageId>000001</packageId>
                <promotionSiteName>SERT8</promotionSiteName>
                <promotionLevel>10</promotionLevel>
                <promotionName>C001AUT</promotionName>
                <packageStatus>6</packageStatus>
                <promoter>USER24</promoter>
                <promotionDate>20090217</promotionDate>
                <promotionTime>105054</promotionTime> 
            </result> 
    .
    .
    .
            <response>
                <statusMessage>CMN8700I - Overlay service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

Exhibit 4-26. PACKAGE PRM_OVLY 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 name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>.
<component> Optional 1 String (256), variable ZMF name of staged component.
- If component is PDS member, this is member name (max 8 bytes, no qualifiers).
- If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentType> Optional 0 - 1 String (3), fixed Library type of staged component.
<isComponentRestaged> Optional 0 - 1 String (1) Y = Yes, component is restaged
N = No, component not restaged
<overlayStatus> Optional 0 - 1 String (1) Code for overlay status of this component in this promotion library. Values:
N = Exists in promotion library but has no history
H = Exists in promotion history but not in promotion library
C = Common to both promotion library and history
<package> Optional 0 - 1 String (10), variable 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>.
<packageStatus> Optional 1 String (1) Code for status of package in lifecycle. Values: = Approved = Backed out = Baselined = Complex/super pkg closed = Deleted (memo delete) = Development = Distributed = Frozen = Installed A = Complex/super pkg open B = Rejected C = Temporary change cycle completed
<promoter> Optional 0 - 1 String (8), variable TSO user ID of latest package promoter.
<promotionDate> Optional 0 - 1 Date, yyyymmdd Latest promotion date for package.
<promotionLevel> Optional 0 - 1 Integer (2), variable Numeric code of promotion level to check for potential component overlays.
<promotionName> Optional 0 - 1 String (8), variable ZMF name of promotion level to check for potential component overlays.
<promotionSiteName> Optional 0 - 1 String (8), variable ZMF name of promotion site to check for potential component overlays.
<promotionTime> Optional 0 - 1 Time, hhmmss Latest promotion time for package, 24hour format.
<release> Optional (ERO only) 0 - 1 String (8), variable Name of release to which package is attached.

Unfreeze Source/Load Components - PACKAGE SRC_LOD UNFREEZE

You can use Serena XML to unfreeze one or more “like-source" or “like-load" components in a package. “Like-copybook" or “like-PDS" components such as copybooks, skeletons, JCL procedures, or ISPF panels are not included in the scope of this function.

The Serena XML service/scope/message tags for a package-level unfreeze message for source and load components are:

These tags appear in both requests and replies.

PACKAGE SRC_LOD UNFREEZE — Requests

Serena XML supports two types of unfreeze requests for source and load components:

  • Full Unfreeze — Unfreezes all source and load component in the named package. This is the default.

  • Selective Unfreeze — Unfreezes a subset of individually named source and/or load components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the itemized components to unfreeze is required in the <listcount> tag.

The following example shows how you might code a full unfreeze request for all components in a package. Data structure details for the <request> tag appear in Exhibit 4-27.

Example XML — PACKAGE SRC_LOD UNFREEZE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SRC_LOD">
        <message name="UNFREEZE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000013</package>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-27. PACKAGE SRC_LOD UNFREEZE <request>

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 Complex identifier for each component to selectively unfreeze or refreeze. See Exhibit 4-28.
NOTE: If used, <listCount> tag also required.
<listCount> Optional 0 - 1 Integer (3), variable Number of components to selectively unfreeze or refreeze. Must match number of <component> tags. Value range: 1 - 800
NOTE: If <component> tag used, this tag is required.
<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>.

The <component\> subtag represents a complex data structure that is frequently reused among the package-level requests in Serena XML. Data structure details for this tag appear in Exhibit 4-28 below.

Exhibit 4-28. <component> Subtag Data Structure

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

PACKAGE SRC_LOD UNFREEZE — Replies

The Serena XML reply to a source and load component unfreeze request does not return a <result\> data structure. It does, however, return a standard <response\> data structure 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.

Example XML — PACKAGE SRC_LOD UNFREEZE Reply

<?xml version="1.0"?>
<service name="PACKAGE"> 
    <scope name="SRC_LOD"> 
        <message name="UNFREEZE"> 
            <response>
                <statusMessage>CMN8700I - UNFREEZE:SRC_LOD service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode> 
                <statusReasonCode>8700</statusReasonCode> 
            </response> 
        </message> 
    </scope>  
</service>

...

Refreeze Source/Load Components - PACKAGE SRC_LOD REFREEZE

The inverse of the Serena XML unfreeze function for source and load components is the refreeze function for these components. Like its inverse, the refreeze function applies to one or more “like-source" or “like-load" components. Other components — copybooks, skeletons, JCL procedures, ISPF panels, and the like — are not included in the scope of this function.

The Serena XML service/scope/message tags for a package-level refreeze message for source and load components are:

<service name="PACKAGE">
<scope name="SRC_LOD">
<message name="REFREEZE">

These tags appear in both requests and replies.

Refreeze Source and Load Components — Requests

As with unfreeze requests, Serena XML supports two types of package-level refreeze requests for source and load components:

  • Full Refreeze — Refreezes all source and load components in the named package. This is the default.

  • Selective Refreeze — Refreezes a subset of individually named source and load components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the itemized components to refreeze is required in the <listcount> tag.

The <request> tag syntax for a source-and-load component refreeze request is identical to that for an source-and-load component unfreeze request. (See Exhibit 4-27.) Only the name parameter in the high-level <message> tag differs in this request, as shown above.

Example XML — PACKAGE SRC_LOD REFREEZE Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="SRC_LOD">
        <message name="REFREEZE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000013</package>
            </request>
        </message>
    </scope>
</service>

...

PACKAGE SRC_LOD REFREEZE — Replies

The Serena XML reply to a source-and-load component refreeze request does not return a <result> data structure. It does, however, return a standard <response> data structure 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.

Example XML — PACKAGE SRC_LOD REFREEZE Reply

<?xml version="1.0"?>
<service name="PACKAGE"> 
    <scope name="SRC_LOD"> 
        <message name="REFREEZE"> 
            <response>
                <statusMessage>CMN8700I - REFREEZE:SRC_LOD service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode> 
            </response>
        </message> 
    </scope>  
</service>

...

Unfreeze Non-Source Components - PACKAGE NON_SRC UNFREEZE

You can use Serena XML to unfreeze one or more “non-source" components in a package. This unfreeze request includes in its scope all “like-load", “like-copybook", and “like-PDS" component library types. “Like-source" components are excluded.

The Serena XML service/scope/message tags for a non-source component unfreeze message are:

<service name="PACKAGE">
<scope name="NON_SRC">
<message name="UNFREEZE">

These tags appear in both requests and replies.

PACKAGE NON_SRC UNFREEZE — Requests

Serena XML supports two types of unfreeze requests for non-source components:

  • Full Unfreeze — Unfreezes all non-source components in the named package. This is the default.

  • Selective Unfreeze — Unfreezes a subset of individually named non-source components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the itemized components to unfreeze is required in the <listcount> tag.

The <request> tag syntax for a non-source component unfreeze request is identical to that for a source-and-load component unfreeze request. (See Exhibit 4-27.) Only the name parameter in the high-level <scope> tag differs in this request, as shown above.

PACKAGE NON_SRC UNFREEZE — Replies

The Serena XML replies to a unfreeze request for non-source components do not return a <result> data structure. They do, however, return a standard <response> data structure 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.

Refreeze Non-Source Components - PACKAGE NON_SRC REFREEZE

The inverse of the Serena XML unfreeze function for non-source components is the refreeze function for these members. Like its inverse, the refreeze function applies to one or more “non-source" components in a package, such as executable load modules, JCL procedures, and copybooks. “Like-source" components are excluded. Scratch and rename utility records are also outside the scope of this function.

The Serena XML service/scope/message tags for a non-source component refreeze message are:

<service name="PACKAGE">
<scope name="NON_SRC">
<message name="REFREEZE">

These tags appear in both requests and replies.

PACKAGE NON_SRC REFREEZE — Requests

Serena XML supports two types of refreeze requests for non-source components:

  • Full Refreeze — Refreezes all non-source components in the named package. This is the default.

  • Selective Refreeze — Refreezes a subset of individually named non-source components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the itemized components to refreeze is required in the <listcount> tag.

The <request> tag syntax for a non-source component refreeze request is identical to that for a non-source component unfreeze request. (See Exhibit 4-27.) Only the name parameter in the high-level <message> tag differs in this request, as shown above.

Refreeze Non-Source Components — Replies

The Serena XML reply to a package-level refreeze request for non-source components does not return a <result> data structure. It does, however, return a standard <response> data structure 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.

List Scratch and Rename Utility Records - CMPONENT PKG_UTIL LIST

Serena XML can list the scratch and rename utility requests for all components in a package. The service/scope/message tags for this list message are:

<service name="CMPONENT">
<scope name="PKG_UTIL"> 
<message name="LIST">

These tags appear in both requests and replies.

The service name is “cmponent", not “package", because XML Services calls the lowlevel component service in ChangeMan ZMF to perform most tasks associated with this function. The scope name, “pkg_util", identifies this message as a package-level component service.

Note

The spelling of “cmponent" in the service name attribute is condensed to eight bytes for legacy compatibility on the mainframe.

CMPONENT PKG_UTIL LIST — Requests

Serena XML supports several uses for the scratch and rename request list. For example, using appropriate selection criteria in your request, you can:

  • Find Old Component Name From New Component Name — Name the desired package in the <package> tag. Enter “8" in the <utilityType> tag to select rename records. Enter the known, new component name (after rename) in the <newComponent> tag. The function returns any rename records that match that new component name, together with the old component name prior to the rename action.

  • Find New Component Name from Old Component Name — Name the desired package in the <package> tag. Enter “8" in the <utilityType> tag to select rename records. Enter the known, old component name (before rename) in the <component> tag. The function returns any rename records that match that old component name, together with the new component name after the rename action.

  • List All Scratched and Renamed Components — Name the desired package in the <package> tag. Enter a blank in the <utilityType> tag or omit it entirely to request both scratch and rename record types. A list of all components with scratch and rename requests, including old and new component names, will be returned.

  • List All Scratched Components — Name the desired package in the <package> tag. Enter “9" in the <utilityType> tag to request scratch records. The functions lists all components in the package with outstanding scratch requests.

To further customize your list request, specify a library type, modification date range, updater ID, or component status of interest. Choose component status options using appropriate yes/no flag tags.

Note

Yes/no flags for component status filtering take default values as a group. The default changes based on whether or not you enter explicit values in these tags, as follows:

  • If no status flag has an explicitly typed value, the default for all tags is “Y".

  • If any status flag has an explicitly typed value, the default for the remaining tags is “N".

The following example shows how you might code a request to list all renamed components in a package using Serena XML. The example request includes only components that were renamed while in unfrozen status; active, inactive, or frozen components are omitted.

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

Example XML — CMPONENT PKG_UTIL LIST Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="PKG_UTIL">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000001</package>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 4-29. CMPONENT PKG_UTIL LIST <request>

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. Use <package> instead of <applName> & <packageId>.
<component> Optional 0 - 1 String (256), variable Original component name before scratch or rename operation. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
NOTE: Takes asterisk (*) wildcard.
<componentType> Optional 0 - 1 String (3), fixed Library type of component in <componentName>.
<filterActiveStatus> Optional 0 - 1 String (1) Y = Include active components
N = Omit active components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterHfsDirectory> Optional 0 - 1 String (256), variable Name of HFS directory containing components to be listed, prefixed by path from installation root (that is, path as stored in baseline library). If present, only files in this directory are listed. If absent, all HFS files meeting other criteria are listed.
NOTE: Applies to z/OS Unix HFS components only. Irrelevant for native z/OS PDS library members.
<filterInactiveStatus> Optional 0 - 1 String (1) Y = Include inactive components
N = Omit inactive components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterUnfrozenStatus> Optional 0 - 1 String (1) Y = Include unfrozen components
N = Omit unfrozen components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<fromDateLastModified> Optional 0 -1 Date, yyyymmdd Start date in desired range of component modification dates.
<newComponent> Optional 0 -1 String (256), variable New component name after rename operation. Blank for scratch operation. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
NOTE: Takes asterisk (*) wildcard.
<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>.
<toDateLastModified> Optional 0 -1 Date, yyyymmdd End date in desired range of component modification dates.
<updater> Optional 0 -1 String (8), variable TSO user ID of last person to update component.
<utilityType> Optional 0 - 1 String (1) Selects type of utility record to list. Values:
8 = Rename record
9 = Scratch record
Blank = Both record types
NOTE: Omit tag or enter explicit blank to list both record types. Null tag returns no records.
NOTE: Asterisk (*) wildcard is not accepted in this tag.

CMPONENT PKG_UTIL LIST — Replies

The Serena XML reply to this request returns zero to many <result> data structures, each of which lists one component scratch or rename utility record for a package. Scratch records report the names of components awaiting deletion, along with status information. Rename records report old and new component names, along with status information for the original component at the time it was renamed.

The reply message returns a standard <response> data structure 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. Because the <response> tag follows the last <result> tag, it also serves as an end-of-list marker.

The example below shows how a reply for this function might appear in Serena XML. Data structure details for the <result> tag appear in Exhibit 4-30.

Example XML — CMPONENT PKG_UTIL LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="PKG_UTIL">
        <message name="LIST">
            <result>
                <utilityType>9</utilityType>
                <package>TES5000001</package>
                <applName>TES5</applName>
                <packageId>000001</packageId>
                <componentType>CPY</componentType>
                <updater>USER24</updater>
                <dateLastModified>20090205</dateLastModified>
                <timeLastModified>112910</timeLastModified>
                <component>ACPCPY00</component>
                <componentStatus>0</componentStatus>
                <encryption>00000000</encryption>
            </result>
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

Exhibit 4-30. CMPONENT PKG_UTIL LIST <result>

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.
<component> Optional 1 String (256), variable Original ZMF name of scratched or renamed component.
- If component is PDS member, this is member name (max 8 bytes, no qualifiers).
- If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentStatus> Optional 0 -1 String (1) Code for original component status. Values:
0 = Active
1 = Approved
2 = Checked Out
3 = Demoted
4 = Frozen
5 = Inactive
6 = Incomplete
7 = Promoted
8 = Refrozen
9 = Rejected
A = Remote Promoted
B = Submitted
C = Unfrozen
<componentType> Optional 1 String (3), variable Library type of scratched or renamed component.
<dateLastModified> Optional 0 - 1 Date, yyyymmdd Date original component was last modified.
<encryption> Optional 0 - 1 String (8), variable Component encryption number
<newComponent> Optional 0 - 1 String (256), variable New ZMF name of renamed component.
<package> Optional 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.
<timeLastModified> Optional 0 - 1 Time, hhmmss Time original component was last modified, 24-hr format.
<updater> Optional 0 - 1 String (8), variable TSO user ID of last person to update original component.
<utilityType> Optional 1 String (1) Code for type of component utility record listed. Values: = Rename record = Scratch record

...

Unfreeze Scratch/Rename Records - PACKAGE SCR_REN UNFREEZE

Unfreeze requests for scratch and rename utility records (the so-called IUTL records) selectively unlock these records so you can scratch and rename package components without otherwise modifying component contents. An audit trail of such actions is maintained in the IUTL records for later listing or impact analysis.

The Serena XML service/scope/message tags for a scratch and rename utility records unfreeze message are:

<service name="PACKAGE">
<scope name="SCR_REN">
<message name="UNFREEZE">

These tags appear in both requests and replies.

PACKAGE SCR_REN UNFREEZE — Requests

Serena XML supports two types of unfreeze requests for scratch and rename utility records:

  • Full Unfreeze — Unfreezes scratch and rename utility records for all components in the named package. This is the default.

  • Selective Unfreeze — Unfreezes a subset of scratch and rename records for individually named components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the components to be unfrozen for scratch or rename purposes is required in the <listcount> tag.

The <request> tag syntax for a scratch and rename unfreeze request is identical to that for other component unfreeze requests. (See Exhibit 4-27.) Only the name parameter in the high-level <scope> and <message> tags differ, as shown above.

PACKAGE SCR_REN UNFREEZE — Replies

The Serena XML reply to a scratch and rename unfreeze request does not return a <result> data structure. It does, however, return a standard <response> data structure 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.

Refreeze Scratch/Rename Records - PACKAGE SCR_REN REFREEZE

The inverse of the Serena XML unfreeze function for scratch and rename records is the refreeze function for these records. The refreeze function returns the scratch and rename utility functions to their previously locked-down condition for frozen package components in

ChangeMan ZMF.

The Serena XML service/scope/message tags for a scratch and rename record refreeze message are:

<service name="PACKAGE">
<scope name="SCR_REN">
<message name="REFREEZE">

These tags appear in both requests and replies.

PACKAGE SCR_REN REFREEZE — Requests

Serena XML supports two types of refreeze requests for scratch and rename utility records:

  • Full Refreeze — Refreezes scratch and rename records for all components in the named package. This is the default.

  • Selective Unfreeze/Refreeze — Refreezes scratch and rename records for a subset of individually named components in the named package. Desired components are itemized by name and library type in the <component> data element. A count of the components to be refrozen is required in the <listcount> tag.

The <request> tag syntax for a scratch and rename refreeze request is identical to that for other component refreeze requests. (See Exhibit 4-27.) Only the name parameter in the highlevel <scope> and <message> tags differ, as shown above.

PACKAGE SCR_REN REFREEZE — Replies

The Serena XML reply to a scratch and rename utility records refreeze request does not return a <result> data structure. It does, however, return a standard <response> data structure 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.