Skip to content

Component Staging Version Management

Staging version functions for general use include the following:

  • List Component Staging Versions - CMPONENT SSV_VER LIST

  • Retrieve Component Staging Version - CMPONENT SSV_VER RETRIEVE

List Component Staging Versions - CMPONENT SSV_VER LIST

The Serena XML service/scope/message tags and attributes for messages to list all staging versions of a component are:

<service name=”CMPONENT”>
<scope name=”SSV_VER”>
<message name=”LIST”>

These tags appear in both requests and replies.

CMPONENT SSV_VER LIST — Requests

The example below shows how you might code a request to list the staging versions of a component. Staging versions may be listed for only one component per request. Data structure details for the list staging versions tag appear in Exhibit 5-25, following the example.

Example XML — CMPONENT SSV_VER LIST Request

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="SSV_VER">
       <message name="LIST">
         <header>
            <subsys>8</subsys>
            <product>CMN</product>
         </header>
         <request>
            <package>CISQ000030</package>
            <componentType>SRC</componentType>
            <component>CI2Q101</component>
         </request>
       </message>
    </scope>
</service>

** Exhibit 5-25. CMPONENT SSV_VER LIST Data Structure

Subtag Use Instances Data Type & Length Values
<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 Unixstyle long file name, optionally prefixed by path from installation root.
<componentType> Required 1 String (3), fixed ZMF library type of component. Must be editable source code (RECFM not ‘U’). Values:
COB
CPY
JCL
SRC
<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.

CMPONENT SSV_VER LIST — Replies

The Serena XML reply message to a component staging versions list request contains zero to many tags. Each contains information about one previously staged version of the requested component. The tag repeats for each staging version of the component.

The standard data structure follows the final tag 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. As the final data element in the reply, the tag also serves as an end-of-list marker.

An example reply to a list staging versions request follows. Data structure details for the list tag appear in Exhibit 5-26.

Example XML — CMPONENT SSV_VER LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
 <scope name="SSV_VER">
   <message name="LIST">
   <result>
    <versionLocation>2</versionLocation>
    <lastUpdater>USER24</lastUpdater>
    <dateLastModified>20081126</dateLastModified>
    <timeLastModified>100700</timeLastModified>
    <changeDesc>BIG SETQUERY PACKAGE</changeDesc>
    <ispfUser>USER24</ispfUser>
    <ispfDateLastModified>20081126</ispfDateLastModified>
    <ispfTimeLastModified>095100</ispfTimeLastModified>
    <ispfUpdateSize>00094</ispfUpdateSize>
    <ispfVersion>001</ispfVersion>
    <ispfModLevel>001</ispfModLevel>
    <ispfInitialDate>20080118</ispfInitialDate>
    <ispfInitialSize>00090</ispfInitialSize>
    <ispfModSize>00000</ispfModSize>
   </result>
   <result>
    <versionLocation>4</versionLocation>
    <lastUpdater>USER24</lastUpdater>
    <dateLastModified>20081126</dateLastModified>
    <timeLastModified>095100</timeLastModified>
    <changeDesc>Baseline version</changeDesc>
    <ispfUser>USER24</ispfUser>
    <ispfDateLastModified>20081126</ispfDateLastModified>
    <ispfTimeLastModified>095100</ispfTimeLastModified>
    <ispfUpdateSize>00094</ispfUpdateSize>
    <ispfVersion>001</ispfVersion>
    <ispfModLevel>001</ispfModLevel>
    <ispfInitialDate>20080118</ispfInitialDate>
    <ispfInitialSize>00090</ispfInitialSize>
    <ispfModSize>00000</ispfModSize>
   </result>
   <response>
    <statusMessage>CMN8700I - SSV service completed</statusMessage>
    <statusReturnCode>00</statusReturnCode>
    <statusReasonCode>8700</statusReasonCode>
   </response>
  </message>
 </scope>
</service>

Exhibit 5-26. CMPONENT SSV_VER LIST Data Structure

Subtag Use Instances Data Type & Length Values
<backupDate> Optional 0 - 1 Date, yyyymmdd Date component version was last backed up.
<backupTime> Optional 0 - 1 Time, hhmmss Time component version was lastbacked up, 24-hour format.
<backupUser> Optional 0 - 1 String (8), variable TSO user ID of most recent user to back up component version.
<changeDesc> Optional 0 - 1 String (35), variable Text description of changes made in this version of component.
<dateLastModified> Optional 0 - 1 Date, yyyymmdd Date component version was last changed.
<fileFormat> Optional 0 - 1 Integer (1) For regular HFS files, the Unix numeric code for data organization and record delimiter. Allowed values:
0 = Not specified
1 = Binary data
2 = New line (NL)
3 = Carriage return (CR)
4 = Line feed (LF)
5 = CR & LF
6 = LF & CR
7 = CR & NL
Note: Always supplied for HFS data files. Irrelevant and omitted for HFS directories, links or aliases, pipes, or sockets, or for non-HFS components.
<ispfDateLastModified> Optional 0 - 1 Date, yyyymmdd Date component version was last changed or staged by ISPF user
<ispfInitialDate> Optional 0 - 1 Date, yyyymmdd Date component version was created.
<ispfInitialSize> Optional 0 - 1 Integer (5), variable Lines of code in version before change.
<ispfModLevel> Optional 0 - 1 Integer (3), variable ISPF 2-byte modification level for component when last staged.
<ispfModSize> Optional 0 - 1 Integer (5), variable Lines of code changed in version.
<ispfTimeLastModified> Optional 0 - 1 Time, hhmmss Time component version was last changed or staged by ISPF user, 24- hour format.
<ispfUpdateSize> Optional 0 - 1 Integer (5), variable Lines of code in version after change.
<ispfUser> Optional 0 - 1 String (8), variable TSO user ID of last ISPF user to change or stage this component when it was the STG version.
<ispfVersion> Optional 0 - 1 Integer (3), variable ISPF 2-byte version number for component when last staged.
<lastUpdater> Optional 0 - 1 String (8), variable TSO user ID of last component updater for this version.
<permissions> Optional 0 - 1 Integer (3), fixed Unix access permissions for HFS file or directory, coded as 3-digit integer, where:
1st digit = owner permissions
2nd digit = group permissions
3rd digit = permissions for all others
Each digit takes one of the following values:
7 - Read, write/rename/delete, execute
6 - Read, write/rename/delete
5 - Read, execute
4 - Read only
3 - Write/rename/delete, execute
2 - Write/rename/delete only
1 - Execute only
0 - No access permitted
NOTE: Always listed for HFS components. Irrelevant and omitted for non-HFS components.
<promotionLevel> Optional 0 - 1 Integer (4), variable ZMF promotion level to which this component was last promoted when it was the STG version.
<promotionName> Optional 0 - 1 String (8), variable ZMF name of promotion level corresponding to level number in \<promotionLevel>.
<promotionSiteName> Optional 0 - 1 String (8), variable ZMF name of site to which this component was last promoted when it was the STG version.
<timeLastModified> Optional 0 - 1 Time, hhmmss Time component version was last changed, 24-hour format.
<versionLocation> Optional 0 - 1 Integer (1) Code for library where this version of the component resides. Values:
2 = Staging library
4 = Baseline library
6 = Staging version backup lib
<versionStamp> Optional 0 - 1 String (8), fixed Hexadecimal time-and-date stamp that uniquely identifies this version of this component.

Retrieve Component Staging Version - CMPONENT SSV_VER RETRIEVE

The Serena XML service/scope/message tags and attributes for messages to retrieve a specific staging version of a component are:

<service name=”CMPONENT”\>

<scope name=”SSV_VER”\>

<message name=”RETRIEVE”\>

These tags appear in both requests and replies.

The staging version retrieve function is a subset of the staging version recover function seen in the ISPF user interface. The retrieve function finds the desired version of a component in the staging version VSAM master, then copies it to a temporary data set for use. The name of the temporary data set is auto-generated and returned in the Serena XML reply message.

The ISPF recover function goes one step further: it copies the auto-generated data set to any data set chosen by the user. The XML retrieve function does not perform this second step.

CMPONENT SSV_VER RETRIEVE — Requests

Data structure details for the staging version retrieve \<request> tag appear in the following table.

Exhibit 5-27. CMPONENT SSV_VER RETRIEVE \<request>

Subtag Use Instances Data Type & Length Values
<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 to retrieve from staging version.

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 pre- fixed by path from installation root.
<componentType> Required 1 String (3), fixed ZMF library type of component. Must be editable source code (RECFM not ‘U’). Values:

COB

CPY

JCL

SRC
<package> Required 1 String (10), variable Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.

NOTE: Leading zeroes required.
<versionStamp> Required 1 String (8), fixed Hexadecimal date/time stamp of particular component version to retrieve.

CMPONENT SSV_VER RETRIEVE — Replies

The Serena XML reply message for the staging version retrieve function returns one <result> for the requested component version, if found. The standard <response> data structure follows the <result> tag 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.

Data structure details for the retrieval <result> tag appear in the following table.

Exhibit 5-28. CMPONENT SSV_VER RETRIEVE <result>

Subtag Use Instances Data Type & Length Values
<backupDate> Optional 0 - 1 Date, yyyymmdd Date component version was last backed up.
<backupTime> Optional 0 - 1 Time, hhmmss Time component version was last backed up, 24-hour format.
<backupUser> Optional 0 - 1 String (8), variable TSO user ID of most recent user to back up component version.
<changeDesc> Optional 0 - 1 String (35), variable Text description of changes made in this version of component.
<dateLastModified> Optional 0 - 1 Date, yyyymmdd Date component version was last changed.
<fileFormat> Optional 0 - 1 Integer (1) For regular HFS files, the Unix numeric code for data organization and record delimiter. Allowed values:
0 = Not specified
1 = Binary data
2 = New line (NL)
3 = Carriage return (CR)
4 = Line feed (LF)
5 = CR & LF
6 = LF & CR
7 = CR & NL
NOTE: Always supplied for HFS data files. Irrelevant and omitted for HFS directories, links or aliases, pipes, or sockets, or for non-HFS components.
<ispfDateLastModified> Optional 0 - 1 Date, yyyymmdd Date component version was last changed or staged by ISPF user.
<ispfInitialDate> Optional 0 - 1 Date, yyyymmdd Date component version was created.
<ispfInitialSize> Optional 0 - 1 Integer (5), variable Lines of code in version before change.
<ispfModLevel> Optional 0 - 1 Integer (3), variable ISPF 2-byte modification level for component when last staged.
<ispfModSize> Optional 0 - 1 Integer (5), variable Lines of code changed in version.
<ispfTimeLastModified> Optional 0 - 1 Time, hhmmss Time component version was last changed or staged by ISPF user, 24- hour format.
<ispfUpdateSize> Optional 0 - 1 Integer (5), variable Lines of code in version after change.
<ispfUser> Optional 0 - 1 String (8), variable TSO user ID of last ISPF user to change or stage this component when it was the STG version.
<ispfVersion> Optional 0 - 1 Integer (3), variable ISPF 2-byte version number for component when last staged.
<lastUpdater> Optional 0 - 1 String (8), variable TSO user ID of last component updater for this version.
<permissions> Optional 0 - 1 Integer (3), fixed Unix access permissions for HFS file or directory, coded as 3-digit integer, where:
1st digit = owner permissions
2nd digit = group permissions
3rd digit = permissions for all others
Each digit takes one of the following values:
7 - Read, write/rename/delete, execute
6 - Read, write/rename/delete
5 - Read, execute
4 - Read only
3 - Write/rename/delete, execute
2 - Write/rename/delete only
1 - Execute only
0 - No access permitted
NOTE: Always listed for HFS components. Irrelevant and omitted for non-HFS components.
<promotionLevel> Optional 0 - 1 Integer (4), variable ZMF promotion level to which this component was last promoted when it was the STG version.
<promotionName> Optional 0 - 1 String (8), variable ZMF name of promotion level corresponding to level number in <promotionLevel>.
<promotionSiteName> Optional 0 - 1 String (8), variable ZMF name of site to which this component was last promoted when it was the STG version.
<tempLib> Optional 0 - 1 String (256), variable Temporary data set name where version is returned.
<timeLastModified> Optional 0 - 1 Time, hhmmss Time component version was last changed, 24-hour format.
<versionLocation> Optional 0 - 1 Integer (1) Code for library where this version of the component resides. Values: 2 = Staging library 4 = Baseline library 6 = Staging version backup lib
2 = Staging library
4 = Baseline library
6 = Staging version backup lib
<versionStamp> Optional 0 - 1 String (8), fixed Hexadecimal time-and-date stamp that uniquely identifies this version of this component.