Skip to content

Component Lifecycle Tasks

The following component lifecycle tasks are supported by Serena XML for general use:

Check Out a Component - CMPONENT SERVICE CHECKOUT

The Serena XML service/scope/message tags and attributes for component checkout messages are:

<service name="CMPONENT"> 
<scope name="SERVICE">
<message name="CHECKOUT">

These tags appear in both requests and replies.

CMPONENT SERVICE CHECKOUT Requests

Serena XML permits concurrent checkout of one or many components. Checkout options apply equally to all named components in the checkout request. For example, all components must have the same library type, must be checked out from the same source (baseline or promotion), and must be checked out to the same target (staging or a personal development library).

The example below shows how you might code a checkout request in Serena XML. In this example, a component is checked out from level 001 of the baseline library into a personal library.

As in all XML examples in this manual, items in bold type are required. A selection of optional subtags is shown in regular type. Nested subtags of a higher-level complex tag are indented relative to that tag. Repeatable tags appear twice for illustration.

Data structure details for the component checkout <request> tag appear in Exhibit 5-1 following the example.

Example XML — CMPONENT SERVICE CHECKOUT Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="CHECKOUT">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000003</package>
                <componentType>CPY</componentType>
                <chkOutSourceLocation>4</chkOutSourceLocation>
                <chkOutMode>O</chkOutMode>
                <basePromoLibLevel>001</basePromoLibLevel>
                <chkOutTargetLocation>1</chkOutTargetLocation>
                <personalLibStorageMeans>6</personalLibStorageMeans>
                <personalLib>USER24.SETQUERY.WORKLOAD</personalLib>
                <jobCard01>//XMLX029B JOB (RWM,T),'DUMP',CLASS=A,MSGCLASS=A</jobCard01>
                <jobCard02>//* JOBCARD2</jobCard02> <jobCard03>//* JOBCARD3</jobCard03>
                <jobCard04>//* JOBCARD4</jobCard04>
                <listCount>0001</listCount>
                <component>ACPCPY00</component>
            </request>
        </message> 
    </scope> 
</service>

...

Exhibit 5-1 CMPONENT SERVICE CHECKOUT <request> Data Structure

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> tag.
NOTE: Trailing blanks required.
<basePromoLibLevel> Required 1 Integer (3), variable Baseline or promotion library level from which component is checked out. Allowed values (must be positive):
Baseline checkouts - 0 to 99
Promotion checkouts - 1 to 999
**NOTES:
<chkOutSourceLocation> is required with this tag to determine whether value is read as a "negative" baseline level or a "positive" promotion level.
If checkout is from baseline (that is, if <chkOutSourceLocation> = 4), default value is 0.
If baseline level for a checkout is not zero, the checkout must be performed in batch mode (that is, with <chkOutMode> = B).
<chkOutMode> Required 1 String (1), fixed Code for component checkout processing mode. Valid values:
O = Online checkout (letter O)
B = Batch checkout

NOTES:

Batch checkout required (value must be B) if personal library for checkout is Librarian or Panvalet (that is, if <personalLibStorageMeans> = 4 or 5).

Batch checkout required (value must be B) if checking out from a backlevel baseline (that is, if <basePromoLibLevel> is not zero and <chkOutSourceLocation> = 4).
<chkOutSourceLocation> Required 1 String (1), fixed Code for location component is checked out from. Valid values:
3 = Checkout from promotion
4 = Checkout from baseline
8 = ERO component Checkout from a prior release
<chkOutTargetLocation> Required 1 String (1), fixed Code for location component is checked out to. Valid values:
1 = Checkout to personal development library
2 = Checkout to staging library
<component> Required 1 - ∞ String (256), variable ZMF name of component to check out. Repeatable to accommodate multicomponent checkouts.

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: Number of instances must equal value in the <listCount> tag.
<componentType> Required 1 String (3), fixed Must be valid ZMF library type. Typical values:
•COB
•CPY
•JCL
•SRC
•LOD
<jobCard01> . . . <jobCard04> Optional 0 - 1 each String (72), fixed JCL statements needed to set job parameters, allocate data sets, & define library concatenations during checkout. If used, all four tags are required. Tags not needed for JCL should be coded as comment (//).

NOTE:* Required for batch checkout — that is, if <chkOutMode> = B
<listCount> Required 1 Integer Number of components to be checked out. Must equal the number of <component> tags that follow.
<lockComponent> Optional 0 - 1 String (1), fixed Y = Yes, lock after checkout
N = No, don’t lock after checkout
<overlayPriorVersion> Optional 0 - 1 String (1), fixed Y = Yes, overlay preexisting component copy in package
N = No, don’t overlay preexisting component copy in package
NOTE: This tag affects the active component copy currently residing in a change package. It does NOT affect any staged versions of that component created by ZMF’s Save Staging Versions (SSV) feature.
<package> Required 1 String (10), fixed Fixed-format name of ZMF package where component resides. First 4 bytes correspond to <applName>. Final 6 bytes correspond to <packageId>.
NOTE: See ChangeMan ZMF User’s Guide for format of package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of <package> tag.
NOTE: Leading zeroes required.
<personalLib> Optional 0 - 1 String (44), variable Name of personal development library for component checkout.
NOTE: Required if checked out to personal development library – that is, if <chkOutTargetLocation> = 1.
<personalLibStorageMeans> Optional 0 - 1 String (1), fixed Code for data set organization of checkout target location. Values:
4 = CA-Librarian
5 = CA-Panvalet
6 = PDS
8 = Sequential
9 = PDSE
H = HFS
NOTE: Required if checked out to personal development library – that is, if <chkOutTargetLocation> = 1.
NOTE: If value is 4 or 5, batch checkout required – that is, <chkOutMode> = B
<promotionSiteName> Optional 0 - 1 String (8), variable ZMF name of promotion site from which component is checked out.
NOTE: Required if checked out from promotion – that is, if value in <chkOutSourceLocation> = 3.
<release> Optional 0 - 1 String (8), variable Name of ZMF release (ERO Option only).
<releaseArea> Optional 0 - 1 String (8), variable Name of the ZMF release area (ERO Option only).
<savePriorVersion> Optional 0 - 1 String (1), fixed Y = Yes, save staging version of preexisting component
N = No, don’t save staging version of preexisting component
NOTE: This tag applies only if ZMF's Save Staging Versions (SSV) feature is installed. It has no effect on whether or not a component checked out from baseline will overlay a preexisting copy of that component in the package.
<suppressNotify> Optional 0 - 1 String (1), fixed Y = Suppress batch notification
N = Allow batch notification
<userVariable01> . . . <userVariable05> Optional 0 - 1 each String (8), variable Five 8-byte custom user variables for component checkout established by ZMF administrator.
<userVariable06> . . . <userVariable10> Optional 0 - 1 each String (72), variable Five 72-byte custom user variables for component checkout established by ZMF administrator.

Tip

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

CMPONENT SERVICE CHECKOUT Replies

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

Component Service Checkin - CMPONENT SERVICE CHECKIN

The Serena XML service/scope/message tags and attributes for component checkin messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="CHECKIN">

These tags appear in both requests and replies.

Batch Component Checkin Versus Online Component Staging

The Serena XML checkin function performs a subset of the "stage" functions of the ISPF user interface. Check-in simply copies files from a development location into a staged change package and updates the component status information — the first step of three in the staging flow. Check-in does not compile or link-edit the checked-in component. Neither does it log source-to-load and other relationships within a package or build any JCL install jobs.

By deferring many elements of the interactive "stage" function to a later time and a different XML function, the checkin function gains the advantage of speed. Speed is vital for batchmode check-in requests that import a large number of components from other environments to ChangeMan ZMF. Up to 9999 components can be checked in to a ChangeMan ZMF change package via a single XML checkin request.

Tip

Batch component checkin for a large number of components should be specified in native Serena XML and submitted for execution via the SERXMLBC batch execution client. (See SERXMLBC – Executing Native XML Service Calls) Source component name tags should be populated via a table-driven preprocessing script or similar automated means if the number of components is very large.

To complete the full "stage to development" process using Serena XML, the checkin function, if successful, should be followed by an XML request to check designated build procedures, which (if successful) should then be followed by an XML component build request. (See Check Designated Build Procedures - CMPONENT APL_DPRC CHECK and Component Service Build - CMPONENT SERVICE BUILD later in this chapter.)

CMPONENT SERVICE CHECKIN Requests

Serena XML permits concurrent checkin of one to many components. Checkin options apply equally to all named components in the checkin request. For example, all components must have the same library type, must be checked out from the same source location, and must be checked in to the same package.

The example below shows how you might code a Serena XML request to check in a source component from a personal library.

Data structure details for the component checkin <request> tag follow in Exhibit 5-2

Example XML — CMPONENT SERVICE CHECKIN Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="CHECKIN">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000003</package>
                <component>ACPCPY00</component>
                <componentType>CPY</componentType>
                <chkInSourceLocation>1</chkInSourceLocation>
                <sourceStorageMeans>6</sourceStorageMeans>
                <sourceLib>USER24.SETQUERY.WORKLOAD</sourceLib>
                <changeDesc>TEST CMPONENT SERVICE CHECKIN</changeDesc>
                <listCount>0001</listCount>
                <targetComponent>ACPCPY00</targetComponent>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-2 CMPONENT SERVICE CHECKIN <request> Data Structure

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> tag.
NOTE: Trailing blanks required.
<changeDesc> Optional 1 String (35) Component change description to include with all newly checked in components.
<chkInSourceLocation> Required 1 String (1) Code for location from which component is checked in. Valid values:
1 = Checkin from development dataset
5 = Checkin from package
7 = Checkin from a temporary sequential dataset (for example, using ZDD Checkin)
E = Edit from package library
<component> Optional 0 - 1 String (256), variable Source 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.
NOTE: If checking in from a sequential file, this tag is required.
<componentType> Required 1 String (3) Library type to assign to checked-in component(s). Must be valid ZMF library type. Typical values:
•COB
•CPY
•JCL
•SRC
•LOD
<listCount> Required 1 Integer Number of components to be checked in. Must immediately precede the first of one or more <targetComponent> tags. Value must equal the number of <targetComponent> tags that follow.
<lockAfterChkin> Optional 1 String (1) Y = Yes, lock component after checkin
N = No, don’t lock component after check in
<package> Required 1 String (10) ZMF fixed-format package name where component should reside.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of <package> tag.
NOTE: Leading zeroes required.
<savePriorStagingVersion> Optional 0 - 1 String (1) Y = Yes, create staging version of preexisting component (if staging versions enabled)
N = No, don’t create a staging version of component
<sourceLib> Optional 0 - 1 String (44) Data set name of library holding component(s) to check in.
NOTE: For HFS component, path and subdirectory where component resides.
<sourceStorageMeans> Optional 0 - 1 String (1) Code for data set organization of checkout target location. Values:
4 = CA-Librarian
5 = CA-Panvalet
6 = PDS
8 = Sequential data set
9 = PDS/Extended
H = HFS
<sourceStorageMeans> Optional 0 - 1 String (1) Code for data set organization of checkout target location. Values:
4 = CA-Librarian
5 = CA-Panvalet
6 = PDS
8 = Sequential data set
9 = PDS/Extended
H = HFS
<suppressNotify> Optional 0 - 1 String (1) Y = Yes, suppress notify messages
N = No, don’t suppress notify messages
<targetComponent> Required 1 - ∞ String (256), variable ZMF name of component to check in. Repeatable for multiple concurrent check-ins. Must be preceded by <listCount> tag.
NOTE: Number of instances must equal value in <listCount>.
NOTE: HFS components must also designate a target subdirectory for checkin in <targetSubDirectory>. For HFS components, all instances must belong to the same subdirectory.
<targetSubDirectory> Optional 0 - 1 String (256), variable Name of the target HFS subdirectory where components are to be checked in, prefixed by path from installation root (that is, path as it is defined in the baseline library).
NOTE: Required for HFS component if <useSourceLibSubDirectory> = N.
NOTE: Only one subdirectory is supported per request. For bulk checkins, all <targetComponent> tagsmust contain components that belong in the same subdirectory.
<userOption01> . . . <userOption20> Optional 0 - 1 each String (1), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 01 to 20 on the ISPF user options panel for component build.
<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.
<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.
<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.
<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.
<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.
<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.
<userOption1601> . . . <userOption1602> Optional 0 - 1 each String (16), variable Administrator-defined build options assigned to component. Each tag corresponds to User Option 1601 to 1602 on the ISPF user options panel for component build.
<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.
<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.
<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.
<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.
<useSourceLibSubDirectory> Optional 0 - 1 String (1) Should target subdirectory & path match source library directory & path?
Y = Use value in <sourceLib> for <targetSubDirectory>.
N = Do not use <sourceLib> for <targetSubDirectory>; supply explicit value instead.
NOTE: <targetSubDirectory> is required if value is N.

Component Service Checkin Reply

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

Check Designated Build Procedures - CMPONENT APL_DPRC CHECK

The Serena XML service/scope/message tags and attributes for a message to check designated component build procedures are:

<service name="CMPONENT">
<scope name="APL_DPRC"> 
<message name="CHECK">

The Serena XML check function performs a subset of the "stage" functions of the ISPF user interface. It checks for the existence of designated build procedures associated with a checked-in component — the second step of three in the staging flow. It does not copy files from a development location into a staged change package. It does not compile or link the checked-in component. Neither does it log source-to-load relationships within a package or build any JCL install jobs.

Tip

To complete the full "stage to development" cycle using Serena XML, first check in the affected component using checkin function. If check-in is successful, followed it with an XML request to check designated build procedures, which (if successful) should then be followed by an XML component build request. (See Check Designated Build Procedures - CMPONENT APL_DPRC CHECK and Component Service Build - CMPONENT SERVICE BUILD later in this chapter.)

CMPONENT APL_DPRC CHECK — Requests

The Serena XML example below shows how you might code a request to check designated component build procedures. Note that you can check build procedures for only one component per request. Data structure details for the <request> tag appear in Exhibit 5-3

...

Example XML — CMPONENT APL_DPRC CHECK Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="APL_DPRC">
        <message name="CHECK">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <component>ACPSRS00</component>
                <componentType>SRS</componentType>
                <applName>ACTP</applName>
                <buildProc>CMNCOB2</buildProc>
                <language>COBOL2</language>
                <useDb2PreCompileOption>N</useDb2PreCompileOption>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-3 Check Component Designated Build Procedures <request>

Subtag Use Instances Data Type & Length Instances
<applName> Required 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of <package> tag.
NOTE: Trailing blanks required.
<buildProc> Required 0 - 1 String (8), variable ZMF name for designated build procedure.
<compileOptions> Optional 0 - 1 String (34), variable Custom compile parameters for named component.
<component> Required 1 String (256), variable ZMF name of component to be checked. 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 1 String (3), fixed Library type of component named in <component>. Must be valid ZMF library type of "like-source." Typical values:
•COB
•CPY
•SRC
<language> Required 0 - 1 String (8), variable Source language of component.
<linkOptions> Optional 0 - 1 String (34), variable Custom link-edit parameters for named component.
<useDb2PreCompileOptio n> Required 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile DB2
<userOption01> . . . <userOption20> Optional 0 - 1 each String (1) Administrator-defined build options assigned to component. Each tag corresponds to User Option 01 to 20 on the ISPF user options panel for component build.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.

Tip

Tags: <userOption01> to <userOption20>, <userOptionsPart1>, <userOptionsPart2>, <userOption0101> to <userOption7205>. See topic "Staging User Options" in the ChangeMan ZMF Customization Guide.

Check Component Designated Build Procedures — Replies

No <result> data structure is returned in the reply message to a check component designated procedures request. However, the standard <response> data structure is returned to indicate the success or failure of the check. In general, the following rules of thumb apply to return codes for the designated build procedure check:

  • 00 – Request successful and designated build procedures found.

  • 04 – Informational message; designated build procedures not found.

  • 08 or higher – Failure to execute request.

Find Designated Build Procedure - CMPONENT APL_DPRC FIND

The Serena XML service/scope/message tags and attributes for messages to find a component’s designated build procedure are:

<service name="CMPONENT">
<scope name="APL_DPRC"> 
<message name="FIND">

These tags appear in both requests and replies.

CMPONENT APL_DPRC FIND — Requests

The Serena XML request to find the designated component build procedure retrieves detailed information from the component history file for a specific component. Data structure details for CMPONENT APL_DPRC FIND request are shown in Exhibit 5-4

Exhibit 5-4 CMPONENT APL_DPRC FIND <request>

Subtag Use Instances Data Type & Length Instances
<applName> Required 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of <package> tag.
NOTE: Trailing blanks required.
<component> Required 0 - 1 String (256), variable ZMF component for which to find the designated build procedure. 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 \ 1 String (3), fixed ZMF library type of component(s) for which to list designated build procedures. Must be "like-source." Typical values:
•COB
•CPY
•SRC

CMPONENT APL_DPRC FIND — Replies

The reply message returns zero or one result tag, detailing the procedure if it exists.The reply data structure is the same as that for CMPONENT APL_DPRC LIST and is described in Exhibit 5-6

List Designated Build Procedures - CMPONENT APL_DPRC LIST

The Serena XML service/scope/message tags and attributes for messages to list designated component build procedures at the application level are:

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

These tags appear in both requests and replies.

CMPONENT APL_DPRC LIST — Requests

The Serena XML request to list designated component build procedures retrieves detailed information from the component history file about all such procedures for any of the following:

  • One explicitly named component.
  • All components of the same type.
  • Any components with names that match a wildcard pattern.

The Serena XML example below shows how you might code a request to list designated component build procedures for all components of type "SRS". The request to list designated component build procedures also supports wildcards and patterns. Data structure details for the <request> tag appear in Exhibit 5-5

Example XML — CMPONENT APL_DPRC LIST Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="APL_DPRC">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <applName>ACTP</applName>
                <component>*</component>
                <componentType>SRS</componentType>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-5 CMPONENT APL_DPRC LIST <request>

Subtag Use Instances Data Type & Length Instances
<applName> Required 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of <package> tag.
NOTE: Trailing blanks required.
<component> Required 0 - 1 String (256), variable ZMF component for which to list designated build procedures. 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: May be masked using standard wildcard characters.
<componentType> Optional 1 String (3), fixed ZMF library type of component(s) for which to list designated build procedures. Must be "like-source." Typical values:
•COB
•CPY
•SRC
<exactMatch> Optional 0 - 1 String (1) Y = Yes- exact match no filtering
N = No - use filtering

...

CMPONENT APL_DPRC LIST — Replies

The reply message listing designated component build procedures returns zero to many <result> data elements. Each <result> tag contains information about one component, taken from the component history file. This information includes component name and type, build procedure name, component source language, compile and link options, and the like.

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

Example XML — CMPONENT APL_DPRC LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="APL_DPRC">
        <message name="LIST">
            <result>
                <component>ACPSRS00</component>
                <componentType>SRS</componentType>
                <applName>ACTP</applName>
                <buildProc>CMNCOB2</buildProc>
                <language>COBOL2</language>
                <useDb2PreCompileOption>N</useDb2PreCompileOption>
                <forceAssignedBuildProc>2</forceAssignedBuildProc>
            </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 5-6.

Exhibit 5-6 CMPONENT APL_DPRC 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> tag.
NOTE: Trailing blanks required.
<buildProc> Optional 0 - 1 String (8), variable ZMF name for designated build procedure.
<compileOptions> Optional 0 - 1 String (34), variable Custom compile parameters for named component.
<component> Optional 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 1 String (3), variable ZMF library type of component.
<forceAssignedBuildProc> Optional 0 - 1 String (1) Force level for enforcement of designated build procedure with this component. Values:
1 = Force before freeze only
2 = Always force
<language> Optional 0 - 1 String (8), variable Source language of component.
<linkOptions> Optional 0 - 1 String (34), variable Custom link-edit parameters for named component.
<useDb2PreCompileOption> Required 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile DB2
<userOption01> . . . <userOption20> Optional 0 - 1 each String (1) Administrator-defined build options assigned to component. Each tag corresponds to User Option 01 to 20 on the ISPF user options panel for component build.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.

Tip

Tags: <userOption01> to <userOption20>, <userOptionsPart1>, <userOptionsPart2>, <userOption0101> to <userOption7205>. See topic "Staging User Options" in the ChangeMan ZMF Customization Guide.

List Global Designated Build Procedures - CMPONENT GBL_DPRC LIST

The Serena XML service/scope/message tags and attributes for messages to list designated component build procedures at the global level are:

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

These tags appear in both requests and replies.

The CMPONENT GBL_DPRC LIST service is identical to the CMPONENT APL_DPRC LIST service except that the <appl_Name> tag is omitted. Refer to List Designated Build Procedures - CMPONENT APL_DPRC LIST.

Component Service Build - CMPONENT SERVICE BUILD

The Serena XML service/scope/message tags and attributes for component build messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="BUILD">

These tags appear in both requests and replies.

The Serena XML component build function performs a subset of the "stage" functions of the ISPF user interface. It compiles (or assembles) and link-edits a package component; logs source-to-load and other relationships between modules within a package; and builds any JCL install jobs. Together these comprise the third step of three in the staging flow. The component build function does not copy files from a development location into a staged change package. Neither does it check for the existence of designated build procedures associated with a checked-in component.

Tip

To perform the full "stage to development" process using Serena XML, start with the check in function. If successful, follow check-in with an XML request to check designated build procedures. If this, too, is successful, submit a Serena XML request to build the component. (See Component Service Checkin - CMPONENT SERVICE CHECKIN and Check Designated Build Procedures - CMPONENT APL_DPRC CHECK earlier in this chapter.)

CMPONENT SERVICE BUILD Request

The following example shows how you might code a build request with Serena XML. Data structure details for the component service build <request> tag follow the example in Exhibit 5-7.

...

Example XML — CMPONENT SERVICE BUILD Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="BUILD"> 
            <header> 
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request> 
                <package>TES5000001</package> 
                <componentType>SRS</componentType> 
                <buildProc>CMNCOB2</buildProc> 
                <language>COBOL2</language>
                <jobCard01>//XMLX029B JOB (RWM,T),'DUMP',CLASS=A,MSGCLASS=A</jobCard01>
                <jobCard02>//* JOBCARD2</jobCard02>
                <jobCard03>//* JOBCARD3</jobCard03>
                <jobCard04>//* JOBCARD4</jobCard04>  
                <listCount>001</listCount> 
                <component>ACPSRS00</component> 
            </request>
        </message>  
    </scope> 
</service>

...

Exhibit 5-7 CMPONENT SERVICE BUILD <request> Data Structure

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> tag.
NOTE: Trailing blanks required.
<buildProc> Optional 0 - 1 String (8), variable 8-byte ZMF name for designated build procedure.
<compileOptions> Optional 0 - 1 String (34), variable Compile parameters not set elsewhere (e.g. in component history) or by default.
NOTE: The <useHistory> tag must be set to N to use this tag.
<component> Required 1 - ∞ String (256), variable ZMF name of component to build. Repeatable to accommodate multiple components. 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: Number of instances must equal the value in the <listCount> tag.
<componentType> Required 1 String (3), fixed Library type of all component(s) to be built. Must be valid ZMF library type of "like-source." Typical values:
•COB
•CPY
•SRC
<db2PreCompileLinkLib> Optional 0 - 1 String (44), variable Data set name of DB2 library to be used in build process.
NOTE: The <useHistory> tag must be set to N to use this tag.
<db2PreCompileVersion> Optional 0 - 1 String (64), variable DB2 DBRM version to use when building components.
NOTE: The <useHistory> tag must be set to N to use this tag.
<db2SubSystemId> Optional 0 - 1 String (4), variable 4-byte physical subsystem ID of DB2 instance to use in build.
NOTE: The <useHistory> tag must be set to N to use this tag.
<incrementJobname> Optional 0 - 1 String (1) Y = Yes, increment the job name
N = No, don’t increment the job name
<inputDataset> Optional 0 - 1 String (44), variable Data set name of staging library where like-source component(s) reside(s).
<jobCard01> . . . <jobCard04> Required 0 - 1, each String (72), variable JCL statements needed to set job parameters, allocate data sets, & define library concatenations. If used, all four are required. Tags not needed for JCL should be coded as comment (//*).
<language> Optional 0 - 1 String (8), variable Source language of component(s) to be compiled. Max 8 bytes.
<linkOptions> Optional 0 - 1 String (34), variable Link edit parameters not set elsewhere (e.g. in component history) or by default.
NOTE: The <useHistory> tag must be set to N to use this tag.
<listCount> Required 1 Integer Number of components to be checked out. Must equal the number of <component> tags that follow.
<package> Required 1 String (10), variable ZMF fixed-format package name where component(s) reside(s).
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
<sourceLocation> Optional 0 - 1 String (1) This tag is used when staging "like type" OTH components from remote clients. Specify the value "7" to indicate that the build source dataset is a temporary dataset and will be deleted when the build process is completed. CAUTION! Do not use this tag unless you are sure you want to delete the input dataset.
<suppressNotify> Optional 0 - 1 String (1) Y = Yes, suppress notify messages
N = No, don’t suppress messages
<useDb2PreCompileOption> Optional 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile DB2
NOTE: The <useHistory> tag must be set to N to use this tag.
<useHistory> Optional 0 - 1 String (1) Y = Yes, use comp hist for compile params (default)
N = No, don’t use comp history
NOTE: This tag must be set to N to use the <useDb2PreCompileOption>, <compileOptions>, <linkOptions>, <db2SubSystemId>, <db2PreCompileLinkLib>, and <db2PreCompileVersion> tags.
<userOption01> . . . <userOption20> Optional 0 - 1, each String (1) Administrator-defined 1-byte user option variables.
NOTE: See your ZMF application administrator for information.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<userOptionsPart1> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userOptionsPart2> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userPanel> Optional 0 - 1 String (8), variable User panel ID.
<userVariable01> . . . <userVariable05> Optional 0 - 1, each String (8), variable Administrator-defined 8-byte user variables, if any, for use with customized skeletons during build.
NOTE: See your ZMF application administrator for information.
<userVariable06> . . . <userVariable10> Optional 0 - 1, each String (72), variable Administrator-defined 72-byte user variables, if any, for use with customized skeletons during build.
NOTE: See your ZMF application administrator for information.

Tip

Tags: <userOption01> to <userOption20>, <userOptionsPart1>, <userOptionsPart2>, <userOption0101> to <userOption7205>. See topic "Staging User Options" in the ChangeMan ZMF Customization Guide.

CMPONENT SERVICE BUILD Replies

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

Tip

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

Recompile a Component - CMPONENT SERVICE RECOMP

The Serena XML service/scope/message tags and attributes for component recompile messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="RECOMP">

These tags appear in both requests and replies.

CMPONENT SERVICE RECOMP Requests

Unlike the component check-in and check-out functions described above, the component recompile function works on only one component per request message. It performs only one task: compilation (or assembly) of the named component.

Note

The component recompile function does not link-edit the named component. That task can be performed on a standalone basis using the Serena XML relink function, described later in this chapter.

The Serena XML example below shows how you might code a request to recompile a component from baseline. For illustration, the example requests a DB2 precompile. Note that DB2-related tags apply only to customers who install the ChangeMan ZMF DB2 Option. Administrator-defined user options and variables with hypothetical values also appear in the example. Check with your ChangeMan ZMF administrator for further information about custom user variables for components. They may not apply to your installation.

Data structure details for the recompile <request> tag appear in Exhibit 5-8

Example XML — CMPONENT SERVICE RECOMP Request

<?xml version="1.0"?> 
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="RECOMP"> 
            <header>  
                <subsys>8</subsys> 
                <product>CMN</product>
            </header>
            <request> 
                <package>TES5000001</package> 
                <componentType>SRS</componentType>  
                <jobCard01>//XMLX034 JOB (RWM,T),'DUMP',CLASS=A,MSGCLASS=A,REGION=0M</jobCard01>
                <listCount>0001</listCount> 
                <component>ACPSRS1B</component>  
                <language>COBOL2</language> 
                <buildProc>CMNCOB2</buildproc>
            </request>
        </message> 
    </scope> 
</service>

...

Exhibit 5-8 CMPONENT SERVICE RECOMP <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.
<buildProc> Optional 0 - 1 String (8), variable 8-byte ZMF name for designated build procedure.
<compileOptions> Optional 0 - 1 String (34), variable Compile parameters not set elsewhere (e.g. in component history) or by default.
<component> Required 1 String (256), variable ZMF name of component to recompile. 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 1 String (3), fixed ZMF "like-source" library type of component to be recompiled. Typical values:
•COB
•CPY
•SRC
<db2PreCompileLinkLib> Optional 0 - 1 String (44), variable Data set name of DB2 library to be used in build process.
<db2PreCompileVersion> Optional 0 - 1 String (64), variable DB2 DBRM version to use when recompiling components.
<db2SubSystemId> Optional 0 - 1 String (4), variable Physical subsystem ID of DB2 instance to use in build.
<jobCard01>

<jobCard02>

<jobCard03>

<jobCard04>		 Required

Optional

Optional

Optional		 1

0 - 1

0 - 1

0 - 1		 String (72)

String (72)

String (72)

String (72)		 JCL statements needed to set job parameters, allocate data sets, & define library concatenations. <jobCard01> is required. Tags not needed for JCL may be omitted.
<language> Optional 0 - 1 String (8), variable Source language of component(s) to be compiled. If omitted, ZMF retrieves from component history.
<libLevel> Optional 1 String (2), variable Numeric library level of source code to recompile. Values:
1 = Baseline library
to 99 = Promotion library
NOTE: <promotionSiteName> tag also required if value > 0.
<linkOptions> Optional 0 - 1 String (34), variable Link edit parameters not set elsewhere (e.g. in component history) or by default.
NOTE: The <useHistory> tag must be set to N to use this tag.
<listCount> Optional 0 - 1 Integer Number of components to be recompiled.
<lockComponent> Optional 0 - 1 String (1) Y = Yes, lock after recompile
N = No, don’t lock component
<overlayPriorVersion> Optional 0 - 1 String (1) Y = Yes, overlay load module in staging library
N = No, don’t overlay
<package> Required 1 String (10), variable ZMF fixed-format package name where component resides.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
<promotionSiteName> Optional 0 - 1 String (8), variable ZMF promotion library site name.
NOTE: If <libLevel> = 1 to 99, this tag is required.
<release> Optional 0 - 1 String (8), variable Name of ZMF release (ERO Option only).
<releaseArea> Optional 0 - 1 String (8), variable Name of the ZMF release area (ERO Option only).
<suppressNotify> Optional 0 - 1 String (1) Y = Yes, suppress notify messages
N = No, don’t suppress messages
<useDb2PreCompileOption> Optional 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile DB2
<useHistory> Optional 0 - 1 String (1) Y = Yes, use comp hist for compile params (default)
N = No, don’t use comp history
NOTE: This tag must be set to N to use the <useDb2PreCompileOption>, <compileOptions>, <linkOptions>, <db2SubSystemId>, <db2PreCompileLinkLib>, and <db2PreCompileVersion> tags.
<userOption01> . . . <userOption20> Optional 0 - 1, each String (1) Administrator-defined 1-byte user option variables.
NOTE: See your ZMF application administrator for information.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<userOptionsPart1> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userOptionsPart2> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userPanel> Optional 0 - 1 String (8), variable User panel ID.
<userVariable01> . . . <userVariable05> Optional 0 - 1 String (8), variable Administrator-defined 8-byte user variables for recompile.
<userVariable06> . . . <userVariable10> Optional 0 - 1 String (72), variable Administrator-defined 72-byte user variables, if any, for use with recompile.

Tip

Tags: <userOption01> to <userOption20>, <userOptionsPart1>, <userOptionsPart2>, <userOption0101> to <userOption7205>. See topic "Staging User Options" in the ChangeMan ZMF Customization Guide.

CMPONENT SERVICE RECOMP Replies

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

Tip

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

The Serena XML service/scope/message tags and attributes for component relink messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="RELINK">

These tags appear in both requests and replies.

The component relink function, like the component recompile function, works on only one component per request message. It performs only one task: link-editing the named component. Prior compilation is assumed.

Note

The component relink function does not compile the named component or change the source code in any way. Compilation (or assembly) can be performed on a standalone basis using the Serena XML recompile function, described earlier in this chapter.

The example below shows how you might code a request to relink a component in Serena XML. Data structure details for the recompile <request> tag appear in Exhibit 5-9.

...

Example XML — CMPONENT SERVICE RELINK Request

<?xml version="1.0"?> 
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="RELINK"> 
            <header> 
                <subsys>8</subsys> 
                <product>CMN</product>  
            </header>
            <request> 
                <package>ACTP000014</package>  
                <component>ACPSRS00</component> 
                <componentType>LOS</componentType> 
                <targetLoadLibType>LOD</targetLoadLibType> 
                <buildProc>CMNCOB2</buildProc> 
                <language>COBOL2</language> 
                <linkOptions>NCAL</linkOptions> 
                <useDb2PreCompileOption>N</useDb2PreCompileOption> 
                <jobCard01>//XMLX035 JOB (AMW,000),'DEFINE UCAT',MSGCLASS=Y,</ jobCard01>
                <jobCard02>// TIME=(,10),NOTIFY=USER24</jobCard02>
            </request>
        </message> 
    </scope> 
</service>

...

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.
<buildProc> Optional 0 - 1 String (8), variable 8-byte ZMF name for designated build procedure.
<compileOptions> Optional 0 - 1 String (34), variable Compile parameters not set elsewhere (e.g. in component history) or by default.
<component> Required 1 String (256), variable ZMF name of component to relink. 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 1 String (3), fixed ZMF "like-source" library type of component to be recompile. Typical values:
•COB
•CPY
•SRC
<db2PreCompileLinkLib> Optional 0 - 1 String (44), variable Data set name of DB2 library to be used in build process.
<db2PreCompileVersion> Optional 0 - 1 String (64), variable DB2 DBRM version to use when recompiling components.
<db2SubSystemId> Optional 0 - 1 String (4), variable Physical subsystem ID of DB2 instance to use in build.
<jobCard01> <jobCard02> <jobCard03> <jobCard04> Required Optional Optional Optional 1 0 - 1 0 - 1 0 - 1 String (72) String (72) String (72) String (72) JCL statements needed to set job parameters, allocate data sets, & define library concatenations. <jobCard01> is required. Tags not needed for JCL may be omitted.
<language> Optional 0 - 1 String (8), variable Source language of component(s) to be compiled. If omitted, ZMF retrieves from component history.
<linkOptions> Optional 0 - 1 String (34), variable Link edit parameters not set elsewhere (e.g. in component history) or by default.
NOTE: The <useHistory> tag must be set to N to use this tag.
<package> Required 1 String (10), variable ZMF fixed-format package name where component resides.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
<targetLoadLibType> Required 0 - 1 String (3), variable Target load library type.
<useDb2PreCompileOption> Optional 0 - 1 String (1) Y = Yes, use DB2 precompile
N = No, don’t precompile DB2
<useHistory> Optional 0 - 1 String (1) Y = Yes, use comp hist for compile params (default)
N = No, don’t use comp history
NOTE: This tag must be set to N to use the <useDb2PreCompileOption>, <compileOptions>, <linkOptions>, <db2SubSystemId>, <db2PreCompileLinkLib>, and <db2PreCompileVersion> tags.
<userOption01> . . . <userOption20> Optional 0 - 1, each String (1) Administrator-defined 1-byte user option variables.
NOTE: See your ZMF application administrator for information.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<userOptionsPart1> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userOptionsPart2> Optional 0 - 1 String (10), variable Administrator-defined component user variables.
<userPanel> Optional 0 - 1 String (8), variable User panel ID.
<userVariable01> . . . <userVariable05> Optional 0 - 1 String (8), variable Administrator-defined 8-byte user variables for recompile.
<userVariable06> . . . <userVariable10> Optional 0 - 1 String (72), variable Administrator-defined 72-byte user variables, if any, for use with recompile.

Tip

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

Tip

Tags: <userOption01> to <userOption20>, <userOptionsPart1>, <userOptionsPart2>, <userOption0101> to <userOption7205>. See topic "Staging User Options" in the ChangeMan ZMF Customization Guide.

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

A successful request will generate a job with output similar to the following:

...

-STEPNAME PROCSTEP     RC   EXCP   CONN   TCB   SRB
-SSIDN                 00     91     46   .00   .00
-ALLOC                 00     14      6   .00   .00
-ALLOCIN               00     38     19   .00   .00
-LINK                  00    125     61   .00   .00
-BT90LOD               00    181     79   .00   .00
-COPYLOD               00    235    555   .00   .00
-SUCCESS               00    649    320   .00   .00
-CHKCOND               00     14      5   .00   .00
-FAILURE            FLUSH      0      0   .00   .00
-PRINT                 00    262    126   .00   .00
-COMPLST               00    137    110   .00   .00
-ILODLST               00    561    301   .00   .00
-XMLX035 ENDED.    NAME-DEFINE   UCAT        TOTAL TCB
$HASP395 XMLX035 ENDED 
.

...

.
*****************************************************************************
* DDNAME: SSIDN.SYSPRINT
*****************************************************************************

ChangeMan(R)       CMNSSIDN - 6.1.0    THURSDAY FEBRUARY 19, 2009 09:17:08
  PARM=''
SYSIN: LCT=ACPSRS00
SYSIN: SSI=5C6D1B0A 
SYSIN: PKG=ACTP000014  
SYSIN: RLK=Y
SYSIN: UIL=Y 
SYSIN: OPT=CALL 
Options compiled from PARM/SYSIN follow: 
  NAME        - Allow "NAME" directive. 
  CALL - Allow "INCLUDE" directives. 
  RELINK - Re-Linkage-Edit by INCLUDEing again. 
END OF DATA ON "OBJ" DETECTED 
STAGING "LCT" OPENED 
STAGING "LCT" MEMBER NOT FOUND  
FABRICATING LCT CARDS FROM SCRATCH

<...+....1....+....2....+....3....+....4....+....5....+....6....+....7
LCT:          INCLUDE INCLIB(ACPSRS00) 
LCT:           SETSSI 5C6D1B0A
LCT:           NAME ACPSRS00(R) 

*****************************************************************************
* DDNAME: LINK.SYSPRINT  
* DDNAME: BT90LOD.BAT90LST
*****************************************************************************

z/OS V1 R8 BINDER         09:17:09 THURSDAY FEBRUARY 19, 2009 
BATCH EMULATOR J  OB(XMLX035 ) STEP(LINK     ) PGM= IEWL 
IEW2278I B352 INVOCATION PARAMETERS - LIST,XREF,MAP,RENT,NCAL 

IEW2322I  1220  1          INCLUDE INCLIB(ACPSRS00) 
IEW2322I  1220  2           SETSSI 5C6D1B0A
IEW2322I  1220  3            NAME ACPSRS00(R) 
IEW2650I  5102 MODULE ENTRY NOT PROVIDED. ENTRY DEFAULTS TO SECTION 
ACPSRS00.

*****************************************************************************
* DDNAME: BT90LOD.SYSPRINT**
*****************************************************************************

ChangeMan(R) CMNBAT90 - 6.1.0 THURSDAY FEBRUARY 19, 2009 09:17:10 SYSIN: PKG=ACTP000014  SYSIN: SLT=LOS
SYSIN: SLT=LOS
SYSIN: SNM=ACPSRS00
SYSIN: SID=USER24
SYSIN: SSI=5C6D1B0A
SYSIN: PRC=CMNCOB2
SYSIN: RLK=YES
SYSIN: SUP=NO
SYSIN: LLT=LOD
SYSIN: SLB=ACTPLOSCMNTP.SERT8.DEV.ACTP.\#000014.LOS
SYSIN: SLB=ACTPLODCMNTP.SERT8.DEV.ACTP.\#000014.LOD
SYSIN: SLB=ACTPLOSCMNTP.SERT8.BASE.ACTP.LOS
SYSIN: SLB=ACTPLODCMNTP.SERT8.BASE.ACTP.LOD
SYSIN: ILB=ACTPLOSCMNTP.SERT8.DEV.ACTP.\#000014.LOS
SYSIN: ILB=ACTPLOSCMNTP.SERT8.BASE.ACTP.LOS
CMN5400I - Time of day at end of job: 09:17:11 - Condition Code on exit: 00

Browse a Component - CMPONENT SERVICE BROWSE

The Serena XML service/scope/message tags and attributes for component service browse messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="BROWSE">

These tags appear in both requests and replies.

The component browse function of ChangeMan ZMF is actually a component download function when accessed via XML. Replies come back as XML documents suitable for offline browsing in a text editor or by XML-aware browser software.

CMPONENT SERVICE BROWSE Request

The example on the next page shows how you might code a component service browse request in Serena XML. Data structure details for the browse <request> tag appear in Exhibit 5-10.

Example XML — CMPONENT SERVICE BROWSE Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="BROWSE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000007</package>
                <component>ACPCPY00</component>
                <componentType>CPY</componentType>
                <trim>Y</trim>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-10 CMPONENT SERVICE BROWSE <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<browseFromOption> Optional 1 String (1) Code for component library to browse. Values:
1 = Browse from package
2 = Browse from baseline
3 = Browse from package if found, otherwise from baseline
NOTE: Options 1 and 3 require the <package> tag to be specified.
<component> Required 1 String (256), variable ZMF name of component to browse. 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 1 String (3) ZMF library type of component to browse.
<hashToken> Optional 0 - 1 String (16) ZMF-generated "fingerprint" of component to browse. If component has changed since the hash token was generated, Serena XML returns a warning.
<package> Required 1 String (10) ZMF fixed-format package name where component resides.
NOTE: This tag is required if <browseFromOption> = 1 or 3.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
<trim> Optional 0 - 1 String (1) Define N if you do not want the trailing blanks to be trimmed before </line> tag
NOTE: Default is Y.

...

CMPONENT SERVICE BROWSE Reply

The component service browse reply returns one <result> tag for the component requested. Component contents are line-oriented in format; that is, each line of component text is returned in its own tag.

A standard <response> data structure follows the <result> tag, if any, to indicate the success or failure of the browse request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. As the last data element returned in a Serena XML reply message, the <response> tag serves as an end-of-list marker.

An example reply to a component service browse request follows.

Example XML — Component Service Browse Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="BROWSE">
            <result> <line> * ACPCPY00.CAP</line>
<line> * ACPCPY00.CAP</line>
<line> 01 ACPCPY00 PIC X(01).</line>
            </result>
            <response> 
                <statusMessage>CMN8700I - Download service completed</statusMessage> 
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

...

Compare Components - CMPONENT SERVICE COMPARE

The Serena XML service/scope/message tags and attributes for component compare messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="COMPARE">

These tags appear in both requests and replies.

CMPONENT SERVICE COMPARE Requests

You can use Serena XML to compare a component in the staging library against a like-named component in any baseline or promotion library. The value in the tag specifies the baseline level (0 to -99) or promotion level (1 to 999) for the comparison.

The example below shows how you might code a request to compare a component in a staged package with a baselined version of that component. Data structure details for the compare <request> tag appear in Exhibit 5-11.

Example XML — CMPONENT SERVICE COMPARE Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="COMPARE">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000001</package>
                <component>ACPCPY00</component>
                <componentType>CPY</componentType>
                <baseLibLevel>001</baseLibLevel>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-11 CMPONENT SERVICE COMPARE <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<baseLibLevel> Required 1 String (3), variable Baseline or promotion library level of component compared against component in staging. Baseline range: 0 to -99 Promotion range: 1 to 999
<component> Required 1 String (256), variable ZMF component to be compared. 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 1 String (3), fixed ZMF library type of component to be compared. Typical values:
•COB
•CPY
•JCL
•LOD
•SRC
<package> Required 1 String (10), variable ZMF fixed-format package name where component resides.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.

...

CMPONENT SERVICE COMPARE Replies

The component package browse reply returns one <result> tag, which contains the component comparison report. Each line of the report is bracketed by a tag.

Example XML — CMPONENT SERVICE COMPARE Reply

...

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE"> 
        <message name="COMPARE">
            <result>
                <line>1 S E R C M P A R (MVS - 560 - 20080929) 2 TEXTONLY FRIDAY**
                    **FEBRUARY 13, 2009 (2009/044) 08:36:47 PAGE 1</line>
                <line>**SYSUT1=CMNTP.A013D.\#C3BDFBA.\#313AB10.WORKSRD(ACPCPY00),SYSUT2=CMNTP.SERT8.D**
                    **EV.TES5.\#000001.CPY(ACPCPY00)</line>
                <line>0 * ACPCPY00.CAP****O N E 1</line>
                <line> * ACPCPY00.CAP****O N E 2</line>
                <line>0++++++++\|+++.++++1++++.++++2++++.++++3++++.++++4++++.++++5++++.++++6**
                    **++++.++++7++++.++++8+++++++++++++++++++++</line>
                <line> I * ADDED 2/13/2009 8:35 AM****DIF T W O 3 +</line>
                <line>**++++++++\|+++.++++1++++.++++2++++.++++3++++.++++4++++.++++5++++.++++6++++.++**
                    **++7++++.++++8+++++++++++++++++++++</line>
                <line></line>
                <line> 01 ACPCPY00 PIC X(01).****O N E 3</line>
                <line>0SER71I - END OF TEXT ON FILE SYSUT1</line>
                <line>0SER72I - END OF TEXT ON FILE SYSUT2</line>
                <line>-SER75I - RECORDS PROCESSED: SYSUT1(3)/****SYSUT2(4),DIFFERENCES(0,0,1)</line>
                <line> EXPLANATION - 0 RECORDS DIFFER THAT****SYNCHRONIZED TOGETHER</line>
                <line> 0 RECORDS WERE CONSIDERED INSERTED ON SYSUT1</line>
                <line>  1 RECORD WAS CONSIDERED****INSERTED ON SYSUT2</line>
                <line>1 S E R C M P A R (MVS - 560 - 20080929) 2 TEXTONLY FRIDAY**
                    **FEBRUARY 13, 2009(2009/044) 08:36:47 PAGE 2</line>
                <line>**SYSUT1=CMNTP.A013D.\#C3BDFBA.\#313AB10.WORKSRD,SYSUT2=CMNTP.SERT8.DEV.TES5.\#0**
                    **00001.CPY</line>
                <line>0SER71I - END OF DIRECTORY ON FILE SYSUT1</line>
                <line>0SER72I - END OF DIRECTORY ON FILE SYSUT2</line>
                <line>0SER78I - MEMBERS PROCESSED: SYSUT1(1)/****SYSUT2(1),DIFFERENCES(1),REJECTED BY FILTERS:
                    SYSUT1(0)/SYSUT2(0)</line>
                <line>0SER80I - TIME OF DAY AT END OF JOB: 08:36:47 - CONDITION CODE ON****EXIT: 4</line>
            </result>  
            <response>
                <statusMessage>CMN8700I - Download service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message> 
    </scope>
</service>

...

Rename a Component - CMPONENT SERVICE RENAME

The Serena XML service/scope/message tags and attributes for component rename messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="RENAME">

These tags appear in both requests and replies.

CMPONENT SERVICE RENAME Requests

The example below shows how you might code a component rename request in Serena XML. Data structure details for the rename <request> tag appear in Exhibit 5-12.

Example XML — CMPONENT SERVICE RENAME Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="RENAME">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000009</package>
                <componentType>CPY</componentType>
                <oldComponent>ACPCPY1B</oldComponent>
                <newComponent>ACPCPY2B</newComponent>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-12 CMPONENT SERVICE RENAME <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<componentType> Required 1 String (3), fixed ZMF library type of renamed component. Typical values:
•COB
•CPY
•JCL
•LOD
•SRC
<newComponent> Required 1 String (256), variable New ZMF name of 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.
<oldComponent> Required 1 String (256), variable Old ZMF name of component to rename. 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.
<package> Required 1 String (10), variable ZMF name of package where component resides.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.

CMPONENT SERVICE RENAME Replies

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

Scratch a Component - CMPONENT SERVICE SCRATCH

The Serena XML service/scope/message tags and attributes for component scratch messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="SCRATCH">

These tags appear in both requests and replies.

Component Scratch Requests

The example on the next page shows how you might code a component scratch request in Serena XML. Data structure details for the scratch <request> tag appear in Exhibit 5-13, following the example.

Example XML — CMPONENT SERVICE SCRATCH Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="SCRATCH">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000009</package>
                <componentType>CPY</componentType>
                <oldComponent>ACPCPY1C</oldComponent>
            </request>
        </message>
    </scope> 
</service>

...

Exhibit 5-13 CMPONENT SERVICE SCRATCH <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<componentType> Required 1 String (3), fixed ZMF library type of component to scratch. Typical values:
•COB
•CPY
•JCL
•LOD
•SRC
<oldComponent> Required 1 String (256), variable Name of component to scratch. 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.
<package> Required 1 String (10), variable ZMF name of package where component resides.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.

CMPONENT SERVICE SCRATCH Replies

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

Lock or Unlock a Component - CMPONENT SERVICE LOCK/UNLOCK

The component lock and unlock functions in Serena XML share identical request and reply data structures nested within their <service>, <scope>, and <message> tags. Only the name attribute of the <message> tag differs.

The service/scope/message tags and attributes for component lock messages are:

<service name="CMPONENT">
<scope name="SERVICE"> 
<message name="LOCK">

The service/scope/message tags and attributes for component unlock messages are:

<service name="CMPONENT">
<scope name="SERVICE">
<message name="UNLOCK">

These tags appear in both requests and replies.

CMPONENT SERVICE LOCK/UNLOCK Requests

The example below shows how you might code a component lock request in Serena XML. An unlock request would be coded similarly, substituting the attribute name="unlock" in the <message> tag. Data structure details for the <request> tag used in both component lock and unlock messages appear in Exhibit 5-14).

Example XML — CMPONENT SERVICE LOCK Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SERVICE">
        <message name="LOCK">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>TES5000001</package>
                <component>ACPCPY00</component>
                <componentType>CPY</componentType>
            </request>
        </message>
    </scope> </service>

...

Exhibit 5-14 CMPONENT SERVICE LOCK <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<component> Required 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> Required 1 String (3), fixed ZMF library type of component. Typical values:
•COB
•CPY
•JCL
•LOD
•SRC
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.

CMPONENT SERVICE LOCK/UNLOCK Replies

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

List Load Module Subroutines - CMPONENT LOD_SUBR LIST

The Serena XML service/scope/message tags and attributes for messages to list information about load module subroutines are:

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

These tags appear in both requests and replies.

CMPONENT LOD_SUBR LIST Requests

The CMPONENT LOD_SUBR LIST request retrieves information about statically linked subroutines within a load module.

The example below shows how you might code a component subroutine list request in Serena XML. Data structure details for the <request> tag appear in Exhibit 5-15.

Example XML — CMPONENT LOD_SUBR LIST Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="LOD_SUBR">
        <message name="LIST">
            <header>
                <subsys>4</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000007</package>
                <compositeComponent>ACPSRC1A</compositeComponent>
                <compositeComponentType>LOD</compositeComponentType>
                <sourceComponent>ACPSRC1A</sourceComponent> <sourceComponentType>SRC</sourceComponentType>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-15 CMPONENT LOD_SUBR LIST <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<compositeComponent> Required 1 String (256), variable ZMF name of load module. 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: Component name may be masked using standard wildcards.
<compositeComponentType> Required 1 String (3), fixed ZMF library type of composite component.
<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.
<sourceComponent> Required 1 String (256), variable ZMF name of source 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.
NOTE: Component name may be masked using standard wildcards.
<sourceComponentType> Required 1 String (3), fixed ZMF library type of source component.

CMPONENT LOD_SUBR LIST Replies

The reply message listing information about a load module and its statically linked subroutines returns zero to many <result> data elements. Each <result> tag contains information about one subroutine within the composite component. This information includes the subroutine name and type, the SETSSI value, and so on.

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

...

Example XML — CMPONENT LOD_SUBR LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="LOD_SUBR">
        <message name="LIST">
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <compositeComponent>ACPSRC1A</compositeComponent>
                <compositeComponentType>LOD</compositeComponentType>
                <sourceComponent>ACPSRC1A</sourceComponent>
                <sourceComponentType>SRC</sourceComponentType>
                <compositeSetssi>61118F95</compositeSetssi>
                <compositeFromIDR>Y</compositeFromIDR>
                <subroutineComponent>ACPSRC1A</subroutineComponent>
                <subroutineComponentAppl>ACTP</subroutineComponentAppl>
                <subroutineComponentType>LOD</subroutineComponentType>
                <subroutinePackage>ACTP000007</subroutinePackage>

...

                <subroutineApplName>ACTP</subroutineApplName>
                <subroutinePackageId>000007</subroutinePackageId>
                <subroutineSetssi>61118F95</subroutineSetssi>
                <subroutineFromIDR>Y</subroutineFromIDR>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <compositeComponent>ACPSRC1A</compositeComponent>
                <compositeComponentType>LOD</compositeComponentType>
                <sourceComponent>ACPSRC1A</sourceComponent>
                <sourceComponentType>SRC</sourceComponentType>
                <compositeSetssi>61118F95</compositeSetssi>
                <compositeFromIDR>Y</compositeFromIDR>
                <subroutineComponent>ACPSRS1B</subroutineComponent>
                <subroutineComponentAppl>ACTP</subroutineComponentAppl>
                <subroutineComponentType>LOS</subroutineComponentType>
                <subroutinePackage>ACTP000007</subroutinePackage>
                <subroutineApplName>ACTP</subroutineApplName>
                <subroutinePackageId>000007</subroutinePackageId>
                <subroutineSetssi>60AFD725</subroutineSetssi>
                <subroutineFromIDR>Y</subroutineFromIDR>
            </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 5-16.

Exhibit 5-16 CMPONENT LOD_SUBR LIST <result> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
<compositeComponent> Required 1 String (256), variable ZMF name of load module. 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.
<compositeComponentType> Required 1 String (3), fixed ZMF library type of composite component.
<compositeFromIDR> Optional 0 - 1 String (1) Indicates if composite information is from IDR.
Y = Yes, information is from IDR.
N = No, information is not from IDR.
<compositeHashToken> Optional 0 - 1 String (16) Composite hash token.
<compositeSetssi> Required 1 String (8) Composite SETSSI value.
<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.
<sourceComponent> Required 1 String (256), variable ZMF name of source 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.
<sourceComponentType> Required 1 String (3), fixed ZMF library type of source component.
<subroutineApplName> Optional 0 - 1 String (4), variable ZMF application name of subroutine.
<subroutineComponent> Required 1 String (256), variable ZMF name of subroutine 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.
<subroutineComponentAppl> Required 1 String (4), variable ZMF application name of subroutine component.
<subroutineComponentType> Required 1 String (3), fixed ZMF library type of subroutine component.
<subroutineFromIDR> Optional 0 - 1 String (1) Indicates if subroutine information is from IDR.
Y = Yes, information is from IDR.
N = No, information is not from IDR.
<subroutineHashToken> Optional 0 - 1 String (16) Subroutine hash token.
<subroutinePackage> Required 1 String (10), fixed Fixed-format ZMF package name of subroutine.
<subroutinePackageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number of subroutine.
<subroutineRelease> Optional 1 String (8), variable Subroutine release name.
<subroutineReleaseArea> Optional 1 String (8), variable Subroutine release area name.
<subroutineSetssi> Required 1 String (8) Subroutine SETSSI value.

...

List Copybook Names in Source - CMPONENT SRC_INCL LIST

The Serena XML service/scope/message tags and attributes for messages to list information about copybooks included within a source component are:

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

These tags appear in both requests and replies.

CMPONENT SRC_INCL LIST Requests

The example below shows how you might code a CMPONENT SRC_INCL LIST request in Serena XML. Data structure details for the <request> tag appear in Exhibit 5-17.

Example XML — CMPONENT SRC_INCL LIST Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SRC_INCL">
        <message name="LIST">
            <header>
                <subsys>4</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000007</package>
                <sourceComponent>ACPSRC1A</sourceComponent>
                <sourceComponentType>SRC</sourceComponentType>
            </request>
        </message>
    </scope>
</service>

...

Exhibit 5-17 CMPONENT SRC_INCL LIST <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
<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.
<sourceComponent> Required 1 String (256), variable ZMF name of source 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.
NOTE: Component name may be masked using standard wildcards.
<sourceComponentType> Required 1 String (3), fixed ZMF library type of source component.

CMPONENT SRC_INCL LIST Replies

The reply message listing information about a source component and its included copybooks returns zero to many <result> data elements. Each <result> tag contains information about one copybook within the source component. This information includes the copybook name and type, the version, and so on.

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

...

Example XML — CMPONENT SRC_INCL LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SRC_INCL">
        <message name="LIST">
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <sourceComponent>ACPSRC1A</sourceComponent>
                <setssi>61118FA5</setssi>
                <srcHashToken>6E1E9BDD0000035A</srcHashToken>
                <includedVersion>01</includedVersion>
                <includedModLevel>01</includedModLevel>
                <includedHashToken>6721849B000000A3</includedHashToken>
                <includedApplName>ACTP</includedApplName>
                <includedComponentType>CPY</includedComponentType>
                <includedComponent>ACPCPY00</includedComponent>
            </result>
            <result>
                <package>ACTP000007</package>
                <applName>ACTP</applName>
                <packageId>000007</packageId>
                <sourceComponent>ACPSRC1A</sourceComponent>
                <sourceComponentType>SRC</sourceComponentType>
                <setssi>61118FA5</setssi>
                <srcHashToken>6E1E9BDD0000035A</srcHashToken>
                <includedVersion>01</includedVersion>
                <includedModLevel>01</includedModLevel>
                <includedHashToken>BDC5C909000000BE</includedHashToken>
                <includedApplName>ACTP</includedApplName>
                <includedComponentType>CPY</includedComponentType>
                <includedComponent>ACPCPY1A</includedComponent>
            </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 5-18.

Exhibit 5-18. CMPONENT LIST <result> Data Structure

Subtag Use Instances Data Type & Length Instances
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
<includedApplName> Required String (4), variable ZMF application name of included component.
<includedComponent> Required 1 String (256), variable ZMF name of included 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.
<includedComponentType> Required 1 String (3), fixed ZMF library type of included component.
<includedHashToken> Required 1 String (16) Hash token of included component.
<includedModLevel> Required 1 Integer (2), fixed Modification level of included component.
<includedVersion> Required 1 Integer (2), fixed Version of included component.
<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.
<release> Optional 0 - 1 String (8), variable Release name.
<releaseArea> Optional 0 - 1 String (8), variable Release area name.
<setssi> Required 1 String (8) SETSSI value of source component.
<sourceComponent> Required 1 String (256), variable ZMF name of source 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.
<sourceComponentType> Required 1 String (3), fixed ZMF library type of source component.
<srcHashToken> Required 1 String (16) Hash token of source component.

...

Count copybook names used by source (baseline I/A or package records) — CMPONENT SRC_INCL COUNT

This function is different to the standard list message (above) in that it works with both baseline I/A information as well as package data. If the target source component is in CHECKOUT status, the function will use baseline I/A information. If it is ACTIVE, it will use the package copybook records to fulfill the request.

The Serena XML service/scope/message tags and attributes for messages to count copybooks used by the source component are:

<service name=”CMPONENT”>
<scope name=”SRC_INCL”>
<message name=”COUNT”>

These tags appear in both requests and replies.

CMPONENT SRC_INCL COUNT Requests

The example below shows how you might code a CMPONENT SRC_INCL COUNT request in Serena XML. Data structure details for the <request> tag appear in CMPONENT SRC_INCL COUNT <request> Data Structure.

Example XML — CMPONENT SRC_INCL COUNT Request

<?xml version="1.0"?>
<service name="CMPONENT">
  <scope name="SRC_INCL">
    <message name="COUNT">
      <header>
        <subsys>4</subsys>
        <product>CMN</product>
      </header>
    <request>
      <package>ACTP000007</package>
      <sourceComponent>ACPSRC1A</sourceComponent>
      <sourceComponentType>SRC</sourceComponentType>
      <lowerCopybookNameMask>        </lowerCopybookNameMask>
      <upperCopybookNameMask>        </upperCopybookNameMask>
    </request>
    </message>
  </scope>
</service>

...

Exhibit 5-19 CMPONENT SRC_INCL COUNT <request> Data Structure

Subtag Use Instances Data Type & Length Values
<package> Required 1 String(10), fixed Fixed-format ZMF package name
<sourceComponent> Required 1 String(256), variable ZMF name of source 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.
NOTE: the name must be specific, no masking.
<sourceComponentType> Required 1 String(3), fixed ZMF library type of source component
<lowerCopybookNameMask> Optional 0-1 String(256), variable Lower bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.

NOTE: Leave blank for full list
<upperCopybookNameMask> Optional 0-1 String(256), variable Upper bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.

NOTE: Leave blank for full list.

CMPONENT SRC_INCL COUNT Replies

The reply message listing information about a source component and the number of its included copybooks returns one <result> data element. The <result> tag contains information about the number of copybooks included by the source component (subject to any lower/upper name masks).

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

Example XML — CMPONENT SRC_INCL COUNT Reply

<?xml version="1.0"?>
<service name="CMPONENT">
<scope name="SRC_INCL">
  <message name="COUNT">
    <result>
      <includedTotal>00000140</includedTotal>
    </result>
    <response>
      <statusMessage>CMN8700I - COUNT service completed</statusMessage>
      <statusReturnCode>00</statusReturnCode>
      <statusReasonCode>8700</statusReasonCode>
    </response>
  </message>
</scope>
</service>

...

Exhibit 5-20 CMPONENT SRC_INCL COUNT <result> Data Structure

Subtag Use Instances Data Type & Length Values
<includedTotal> Required 1 Integer(8), fixed Count of copybooks included by this source component (subject to any copybook name masking requirements)

List copybook names used by source (baseline I/A or package records) — CMPONENT SRC_INCL NOLOCATE

This function is different to the standard list message (above) in that it works with both baseline I/A information as well as package data. If the target source component is in CHECKOUT status the function will use baseline I/A information. If it is ACTIVE then it will use the package copybook records to fulfill the request. This request will not obtain physical inventory location information (i.e. “no locate”) and is much more effective (in terms of resources used) than the following “locate” request.

The Serena XML service/scope/message tags and attributes for messages to list with nolocate copybooks used by the source component are:

<service name=”CMPONENT”>
<scope name=”SRC_INCL”>
<message name=”NOLOCATE”>

These tags appear in both requests and replies.

CMPONENT SRC_INCL NOLOCATE Requests

The example below shows how you might code a CMPONENT SRC_INCL NOLOCATE request in Serena XML. Data structure details for the tag appear in CMPONENT SRC_INCL NOLOCATE Data Structure.

Example XML — CMPONENT SRC_INCL NOLOCATE Request

<?xml version="1.0"?>
<service name="CMPONENT">
  <scope name="SRC_INCL">
    <message name="NOLOCATE">
      <header>
        <subsys>4</subsys>
        <product>CMN</product>
      </header>
      <request>
        <package>ACTP000007</package>
        <sourceComponent>ACPSRC1A</sourceComponent>
        <sourceComponentType>SRC</sourceComponentType>
        <lowerCopybookNameMask>         </lowerCopybookNameMask>
        <upperCopybookNameMask>         </upperCopybookNameMask>
      </request>
    </message>
  </scope>
</service>

...

Exhibit 5-21 CMPONENT SRC_INCL NOLOCATE <request> Data Structure

Subtag Use Instances Data Type & Length Instances
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<sourcecomponent> Required 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.
NOTE: The name must be specific, no masking.
<sourcecomponentType> Required 1 String (3), fixed ZMF library type of source component.
<lowerCopybookNameMask> Optional 0-1 String (256), variable Lower bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.
NOTE: Leave blank for full list
<upperCopybookNameMask> Optional 0 - 1 String(256), variable Upper bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.
NOTE: Leave blank for full list

CMPONENT SRC_INCL NOLOCATE Replies

The reply message listing information about a source component and its included copybooks returns zero to many <result> data elements. Each <result> tag contains information about one copybook within the source component. This information includes the copybook name and type, its application, and the total number of copybooks reported.

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

Example XML — CMPONENT SRC_INCL NOLOCATE Reply

<?xml version="1.0"?>
<service name="CMPONENT">
  <scope name="SRC_INCL">
    <message name="NOLOCATE">
      <result>
        <includedTotal>00000140</includedTotal>
        <includedApplName>ACTP</includedApplName>
        <includedComponentType>CPY</includedComponentType>
        <includedComponent>ACPCPY00</includedComponent>
      </result>
      <result>
        <includedTotal>00000140</includedTotal>
        <includedApplName>ACTP</includedApplName>
        <includedComponentType>CPY</includedComponentType>
        <includedComponent>ACPCPY1A</includedComponent>
      </result>  </message>
.
.
.
      <response>
        <statusMessage>CMN8700I - NOLOCATE service completed</statusMessage>
        <statusReturnCode>00</statusReturnCode>
        <statusReasonCode>8700</statusReasonCode>
      </response>
    </message>
  </scope>
</service>

...

Exhibit 5-22 CMPONENT SRC_INCL NOLOCATE <result> Data Structure

Subtag Use Instances Data Type & Length Instances
<includedTotal> Required 1 Integer(8), fixed Count of copybooks included by this source component (subject to any copybook name masking requirements)
<includedApplName> Required 1 String(4), fixed ZMF application associated with this copybook
<includedComponentType> Required 1 String (3), fixed ZMF library type associated with this copybook
<includedComponent> Required 1 String (256), variable ZMF name of included component
If component is PDS member, this is membr 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.

List copybook names used by source (baseline I/A or package records) — CMPONENT SRC_INCL LOCATE

This function is different to the standard list message (above) in that it works with both baseline I/A information as well as package data. If the target source component is in CHECKOUT status the function will use baseline I/A information. If it is ACTIVE then it will use the package copybook records to fulfill the request. This request obtains physical inventory location information and is more resource intensive than the previous NOLOCATE request.

The Serena XML service/scope/message tags and attributes for messages to list with locate copybooks used by the source component are:

<service name=”CMPONENT”>
<scope name=”SRC_INCL”>
<message name=”LOCATE”>

These tags appear in both requests and replies.

CMPONENT SRC_INCL LOCATE Requests

The example below shows how you might code a CMPONENT SRC_INCL LOCATE request in Serena XML. Data structure details for the <request> tag appear in CMPONENT SRC_INCL LOCATE <request> Data Structure.

Example XML — CMPONENT SRC_INCL LOCATE Request

<?xml version="1.0"?>
<service name="CMPONENT">
  <scope name="SRC_INCL">
    <message name="LOCATE">
      <header>
        <subsys>4</subsys>
        <product>CMN</product>
      </header>
      <request>
        <package>ACTP000007</package>
        <sourceComponent>ACPSRC1A</sourceComponent>
        <sourceComponentType>SRC</sourceComponentType>
        <lowerCopybookNameMask>        </lowerCopybookNameMask>
        <upperCopybookNameMask>        </upperCopybookNameMask>
      </request>
    </message>
  </scope>
</service>

...

Exhibit 5-23 CMPONENT SRC_INCL LOCATE Data Structure

Subtag Use Instances Data Type & Length Instances
<package> Required 1 String(10), fixed Fixed-format ZMF package name
<sourceComponent> Required 1 String(256), variable ZMF name of source 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.
NOTE: The name must be specific, no masking.
<sourceComponentType> Required 1 String(3), fixed ZMF library type of source component
<lowerCopybookNameMask> Optional 0 - 1 String(256), variable Lower bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.

NOTE: Leave blank for full list
<upperCopybookNameMask> Optional 0 – 1 String(256), variable Upper bound name mask (explicit name or terminate with asterisk) for range of copybooks to be considered.

NOTE: Leave blank for full list

CMPONENT SRC_INCL LOCATE Replies

The reply message listing information about a source component and its included copybooks returns zero to many <result> data elements. Each <result> tag contains information about one copybook within the source component. This information includes the copybook name and type, its application, specific information about the first found inventory location of the copybook, and the total number of copybooks reported..

The standard <response> data element follows any <result> tags in the reply and indicates the success or failure of the list request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because it is the final data element in the XML reply message, the <response> tag serves as an end-of-list marker.

Example XML — CMPONENT SRC_INCL LOCATE Reply

...

<?xml version="1.0"?>
<service name="CMPONENT">
  <scope name="SRC_INCL">
    <message name="LOCATE">
      <result>
        <includedTotal>00000140</includedTotal>
        <whereFrom>B</whereFrom>
        <includedApplName>ACTP</includedApplName>
        <includedComponentType>CPY</includedComponentType>
        <includedComponent>ACPCPY00</includedComponent>
        <includedComponentLocation>CMNDEV.BASE.CPY</includedComponentLocation>
      </result>
      <result>
        <includedTotal>00000140</includedTotal>
        <whereFrom>P</whereFrom>
        <includedApplName>ACTP</includedApplName>
        <includedComponentType>CPY</includedComponentType>
        <includedComponent>ACPCPY1A</includedComponent>
        <includedComponentLocation>CMNDEV.UNIT.CPY</includedComponentLocation>
      </result> </message>
      <response>
        <statusMessage>CMN8700I - LOCATE service completed</statusMessage>
        <statusReturnCode>00</statusReturnCode>
        <statusReasonCode>8700</statusReasonCode>
      </response>
    </message>
  </scope>
</service>

...

Exhibit 5-24 CMPONENT SRC_INCL LOCATE Data Structure

Subtag Use Instances Data Type & Length Instances
<includedTotal> Required 1 Integer(8), fixed Copy of copybooks included by this source component (subject to any copybook name masking requirements)
<wherefrom> Required 1 String(1), fixed Where this copybook was first found (general inventory location identifier)
  • S – staging library
  • P – promotion library
  • B – baseline library
  • R – release area library
<includedApplName> Required 1 String(4), fixed ZMF application associated with this copybook
<includedComponentType> Required 1 String(3), fixed ZMF library type associated with this copybook
<includedComponent> Required 1 String(256), variable ZMF name of included 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.
<includedComponentLocation> Required 1 String(1024), variable The specific library (or zFS directory) where the copybook was first found.

...