Site Administration
Serena XML supports the following remote site administration tasks for general use:
-
List Globally Defined Remote Sites - SITE GBL LIST
-
List Remote Sites for Application - SITE APPL LIST
-
List Install Calendar for Site - CALENDAR SERVICE LIST
The syntax that identifies these functions appears in the name attribute of the <service> tag, as follows:
<service name="SITE">
<service name="CALENDAR">
The site-oriented scope of the installation calendar service is implicit rather than explicit.
List Globally Defined Remote Sites - SITE GBL LIST
This function lists all globally defined remote sites known to the current instance of
ChangeMan ZMF. Also returned are global specifications for the z/OS logical unit and ChangeMan ZMF subsystem ID associated with that site, the staging library model for the site, the delay library, and site settings for peg dates, file transfer methods, and job cards. If no sites have been defined, no <result> tags are returned in the reply message.
The Serena XML service/scope/message tags and attributes for messages to list globally defined remote sites are:
<service name="SITE">
<scope name="GBL">
<message name="LIST">
These tags appear in both requests and replies.
SITE GBL LIST — Requests
This Serena XML function accepts a single, optional tag in the <request> date element of the request message. That tag, <siteName>, is used when global site specifications are requested for a single site. To request a list of specifications for all sites, enter a "match-all" wildcard character in this tag or omit it altogether.
If you omit the <siteName> tag from the request message, you must still include an empty <request> tag in your request message. The <request> tag is required to identify the message as a request rather than a reply.
Note
XML syntax allows both a long form and a short form for empty tags. An empty <request> tag can therefore be coded in one of two ways.
Long form:
<request>
</request>
<request\>
Data structure details for the <request> data element appear in the following table.
Exhibit 11-9. SITE GBL LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <siteName> | Optional | 0 - 1 | String (8), variable | ZMF name of remote site. NOTE: Use asterisk (*) wildcard or omit tag to request all sites. |
SITE GBL LIST — Replies
The reply message for this function returns zero to many <result> data elements. Each <result> tag contains global specifications for one remote site known to the queried instance of ChangeMan ZMF.
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.
Data structure details for the <result> tag appear in the following table.
Exhibit 11-10. SITE GBL LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <cmnSubSystemId> | Optional | 0 - 1 | String (1) | Subsystem ID of ZMF started task on remote site. |
| <defaultUnitName> | Optional | 0 - 1 | String (8), variable | Default DASD unit name assigned to site partition on remote site. |
| <defaultVolume> | Optional | 0 - 1 | String (6), variable | Default DASD volume assigned to site partition on remote site. |
| <delayLib> | Optional | 0 - 1 | String (255), variable | Fully qualified dataset name of temporary library that receives ZMF data transfers to site. |
| <displayOrderNo> | Optional | 0 - 1 | Integer (undefined) | Display order number. This numeric value dictates the default order in which a list of items is displayed. |
| <gregorianPegDate> | Optional | 0 - 1 | Date (8), yyyymmdd | Peg date expressed as Gregorian date. NOTE: Must be equivalent to value in <julianPegDate> tag. |
| <jesNodeName> | Optional | 0 - 1 | String (8), variable | Site JES node name. |
| <jobCard01> | Optional | 0 - 1 | String (72), variable | First of up to 4 default job cards for application installation at this site. |
| <jobCard02> | Optional | 0 - 1 | String (72), variable | Second of up to 4 default job cards for application installation at this site. |
| <jobCard03> | Optional | 0 - 1 | String (72), variable | Third of up to 4 default job cards for application installation at this site. |
| <jobCard04> | Optional | 0 - 1 | String (72), variable | Fourth of up to 4 default job cards for application installation at this site. |
| <julianPegDate> | Optional | 0 - 1 | String (7), yyyyddd | Peg date expressed in Julian day format. NOTE: Must be equivalent to value in <gregorianPegDate> tag. |
| <logicalUnitName> | Optional | 0 - 1 | String (8), variable | z/OS logical unit name associated with ZMF remote site. |
| <serparmDsn> | Optional | 0 - 1 | String (44) | SERPARM dataset name. |
| <siteName> | Optional | 0 - 1 | String (8), variable | ZMF name of remote site. |
| <siteServerIpAddress> | Optional | 0 - 1 | String (32), variable | Site server IP Address. |
| <siteServerPortID> | Optional | 0 - 1 | String (5), variable | Site server port id. |
| <siteStageLibModel> | Optional | 0 - 1 | String (32), variable | Name of staging library on local ZMF server to use as model for creation & setup of staging library at this remote site. |
| <siteTimeDifference> | Optional | 0 - 1 | String (5), ±hhss | Signed integer representing site time zone offset from Universal Time (UT) in hours & seconds. |
| <xferVehicle> | Optional | 0 - 1 | String (1) | Code for mainframe-to-mainframe file transfer tool. Values: 1 = IEBCOPY 2 = Other (such as XCOM, BDT, or CONNECT:Direct) NOTE: Value of 1 (IEBCOPY) is valid only if DASD shared between development site & remote site. |
List Remote Sites for Application - SITE APPL LIST
This function lists one or all remote sites defined for a named application in the current instance of ChangeMan ZMF. Also returned are the default job cards for installing application-specific packages at the listed site. If no sites have been defined for the named application, no <result> tags are returned in the reply message.
The Serena XML service/scope/message tags and attributes for messages to list remote sites for an application are:
<service name="SITE">
<scope name="APL">
<message name="LIST">
These tags appear in both requests and replies.
SITE APPL LIST — Requests
Serena XML lets you list one or all sites defined for an application. Only the application name is required as input to the request. Specify a site name to restrict results to applicationspecific information about a single site.
Data structure details for the <request> data element appear in the following table.
Exhibit 11-11. SITE APPL LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Required | 1 | String (4), variable | ZMF name of desired application. NOTE: OK to omit trailing blanks. |
| <siteName> | Optional | 0 - 1 | String (8), variable | ZMF name of desired site. |
SITE APPL LIST — Replies
The reply message listing an application’s remote sites returns zero to many <result> data elements. Each <result> tag contains the name of one site defined for that application.
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.
Data structure details for the <result> tag appear in the following table.
Exhibit 11-12. SITE APPL LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Optional | 1 | String (4), variable | ZMF application name. |
| <displayOrderNo> | Optional | 0 - 1 | Integer (undefined) | Display order number. This numeric value dictates the default order in which a list of items is displayed. |
| <jobCard01> | Optional | 0 - 1 | String (72), variable | First of up to 4 default job cards for application installation at this site. |
| <jobCard02> | Optional | 0 - 1 | String (72), variable | Second of up to 4 default job cards for application installation at this site. |
| <jobCard03> | Optional | 0 - 1 | String (72), variable | Third of up to 4 default job cards for application installation at this site. |
| <jobCard04> | Optional | 0 - 1 | String (72), variable | Fourth of up to 4 default job cards for application installation at this site. |
| <jobCards> | Optional | 0 - 4 | String (72), variable | Use tags jobCard01 - joCard04 instead. |
| <siteName> | Required | 1 | String (8), variable | ZMF name of one site associated with named application. |
List Install Calendar for Site - CALENDAR SERVICE LIST
This function lists the package installation schedule for one or all sites defined to
ChangeMan ZMF. If no installs are scheduled for the next 364 days, no results are returned.
Note
Systemwide calendar and scheduler settings are managed via global parameter settings. See List Global Parameters - PARMS GBL LIST for more information about global calendar & scheduler settings.
The Serena XML service/scope/message tags and attributes for messages to list the installation calendar for one or more sites are:
<service name="CALENDAR">
<scope name="SERVICE">
<message name="LIST">
These tags appear in both requests and replies.
CALENDAR SERVICE LIST — Requests
Serena XML supports two types of installation calender list requests:
-
Site Calendar — Request the install calendar for one site by entering the site name in the <siteName> tag of the <request> data element. The number of package installs for that site are returned by date for the next 364 days.
-
Composite Calendar — Request a composite install calendar for all sites by entering a match-all (asterisk) wildcard in the <siteName> tag or omitting the tag altogether. The total number of package installs for the organization are returned by date for the next 364 days. No site breakout is included.
Data structure details for the <request> data element appear in the following table.
Exhibit 11-13. CALENDAR SERVICE LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <siteName> | Optional | 0 - 1 | String (8), variable | ZMF site name. NOTE: Use asterisk (*) wildcard character or omit tag to request schedule for all sites, with no site breakdown. |
CALENDAR SERVICE LIST — Replies
The reply message for this function returns one <result> data element, which contains up to 364 scheduling calendar records. Each record totals the planned number of package install jobs for the site named in the request message, or for the entire organization if no site was named.
The standard <response> data element follows the <result> tag 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.
Data structure details for the <result> tag appear in the following table.
Exhibit 11-14. CALENDAR SERVICE LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <calendarEntry> | Optional | 0 - 364 | Complex | See <calendarEntry> Subtag Data Structure. |
The <result> data element contains a complex subtag,
Exhibit 11-15. <calendarEntry> Subtag Data Structure
| Seq | Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|---|
| 1 | <calendarDate> | Required | 1 | Date, yyyymmdd | Date for install jobs to run. |
| 2 | <numberOfDays> | Required | 1 | Integer (4), variable | Number of days |
| 3 | <scheduledInstallCount> | Required | 1 | Integer (3), variable | Number of package install jobs scheduled for date. |
| 4 | <maximumInstallCount> | Required | 1 | String (3), variable | Maximum number of install jobs set for date by ZMF administrator. NOTE: An unlimited number of packages may be installed if this value = ‘UNL’. |