Skip to content

Sample XMLSERV Session

The following exercise walks you through a sample XMLSERV session. In this exercise, you will do the following:

  • Start XMLSERV.

  • Change the dataset member name for your XML documents to a temporary value.

  • Identify the ChangeMan ZMF subsystem that will execute your XML request.

  • Specify a test setting.

  • Request a general package search using Serena XML.

  • Browse the ChangeMan ZMF package search results in Serena XML format.

  • Exit XMLSERV.

Step 1: Start XMLSERV

To start XMLSERV, first start ISPF. At the ISPF command line or Option ==> prompt, type:

TSO XMLSERV

Note

If XMLSERV does not start with this command, check with the ChangeMan ZMF administrator who installed XMLSERV for the correct library and/or member name.

XMLSERV establishes connections with the resources it requires, then displays the main screen. In this screen, XMLSERV displays its default parameter settings and lists the XML functions you can choose to execute in this session.

File      Help
-----------------------------------------------------------------------------
                        XML Services                           Row 1 from 347 
Command ===> _______________________________________________ SCROLL ===> CSR 
Member .. TEMPNAME Test .. _ Subsys .. 7 
 S Service  Scope    Message  Color    Copybook   Product 
__ APPROVER APL      CREATE   Y        ****AAPR   CMN
__ APPROVER APL      DELETE   Y        ****AAPR   CMN
__ APPROVER APL      LIST     G        ****AAPR   CMN
__ APPROVER APL      UPDATE   Y        ****AAPR   CMN
__ APPROVER PKG      CREATE   Y        ****PAPR   CMN
__ APPROVER PKG      DELETE   Y        ****PAPR   CMN
__ APPROVER PKG      LIST     G        ****PAPR   CMN
__ APPROVER PKG      UPDATE   Y        ****PAPR   CMN
__ BASELIB  SERVICE  LIST     G        ****BASL   CMN
__ CALENDAR SERVICE  LIST     G        ****CLDR   CMN
__ CALENDAR SERVICE  SUMMARY  G        ****CLDR   CMN
__ CMPONENT GBL_DPRC LIST     G        ****GDCP   CMN
__ CMPONENT APL_DPRC CHECK    G        ****ADCP   CMN
__ CMPONENT APL_DPRC FIND     G        ****ADCP   CMN
__ CMPONENT APL_DPRC LIST     G        ****ADCP   CMN
__ CMPONENT GBL_SECR LIST     G        ****GCSC   CMN
__ CMPONENT APL_SECR CHECK    G        ****ACSC   CMN
__ CMPONENT APL_SECR LIST     G        ****ACSC   CMN
__ CMPONENT APL_SECR FIND     G        ****ACSC   CMN
__ CMPONENT APL      CHECK    G        ****CAPP   CMN
__ CMPONENT APL      LIST     G        ****CAPP   CMN
__ CMPONENT CHG_DESC LIST     G        ****PSVD   CMN
__ CMPONENT GBL_CDSC LIST     G        ****GCGD   CMN
__ CMPONENT APL_CDSC LIST     G        ****ACGD   CMN
__ CMPONENT APL_CDSC FIND     G        ****ACGD   CMN
__ CMPONENT HISTORY  CREATE   R        ****CHIS   CMN
__ CMPONENT HISTORY  DELETE   R        ****CHIS   CMN

Step 2: Select an XML Service

The default parameters for your XMLSERV request appear at the top of the XMLSERV main screen. They include the member name where XML request and response documents should be saved, a setting for the diagnostic trace ("Test") option, and the ChangeMan ZMF subsystem to use. You can override these defaults for the duration of your XMLSERV session.

Note

Generally, you should leave the "Test" field blank (i.e., no diagnostic trace data is collected for the SYSOUT log). Blank is the default. However, if you want to run your XML request in test mode and collect trace diagnostics in the ChangeMan ZMF SYSOUT log file, enter a "T" in the "Test" field.

  1. Set the XMLSERV session parameters:

    1. Tab to the Member field in the upper right corner of the screen. The default XML input member name in this case is TEMPNAME. Change it to PACKSRCH.

    2. Tab to the Test field. Ensure that this value is blank — meaning no diagnostic trace is desired.

    3. Tab to the Subsystem field. Change the default subsystem ID to that used by your ChangeMan ZMF instance.

      Note

      For this exercise, the screen prints will show a subsystem ID of Z and an application name of DEMO.

  2. Enter an XMLSERV command to find the PACKAGE.SEARCH.GENERAL function.

    At the Command ---> prompt, type FIND PACKAGE GENERAL SEARCH, and press Enter. XMLSERV skips down to the first service with a Service name of PACKAGE.

  3. Select the XML function you wish to execute.

    Type an S in the S(elect) column in the row for PACKAGE.GENERAL.SEARCH.

    File      Help
-----------------------------------------------------------------------------
                        XML Services                          Row 85 from 194 
Command ===> _______________________________________________ SCROLL ===> HALF 
Member .. TEMPNAME Test .. _ Subsys .. 7 
Member .. PACKSRCH Test .. Subsys .. Z Product .. CMN
 S Service   Scope    Message  Color    Copybook  
__ PACKAGE   CMPONENT INTEGRTY G        ****PINT
__ PACKAGE   FORMS    REFREEZE G        ****PFRZ
__ PACKAGE   FORMS    UNFREEZE G        ****PFRZ
__ PACKAGE   GEN_DESC LIST     G        ****PDSC
__ PACKAGE   GEN_PRMS LIST     G        ****PGPM
__ PACKAGE   GEN_PRMS REFREEZE G        ****PFRZ
__ PACKAGE   GEN_PRMS UNFREEZE G        ****PFRZ
 S PACKAGE   GENERAL  SEARCH   G        ****PSCH
__ PACKAGE   IMP_INST LIST     G        ****PIMI
__ PACKAGE   IMS_ACB  LIST     G        ****PIAS
__ PACKAGE   IMS_CRGN LIST     G        ****PICR
__ PACKAGE   LIMBO    SEARCH   G        ****PSCH
__ PACKAGE   NON_SRC  REFREEZE G        ****PFRZ
__ PACKAGE   NON_SRC  UNFREEZE G        ****PFRZ
__ PACKAGE   PKG_LINK LIST     G        ****PLNK
__ PACKAGE   PKG_LINK SEARCH   G        ****PSCH
__ PACKAGE   PRM_CMP  LIST     G        ****PPRC

  4. Press Enter.

Step 3: Edit the XML Input Document

XMLSERV starts an ISPF edit session for the PACKSRCH member and displays an XML request template. The template contains all valid Serena XML tags predefined for use with the function you selected on the main screen. Most tags are optional and need not be used.

In this example, XMLSERV displays XML tags for the "Package General Search" function.

Your screen should look something like the following:

File  Edit  Edit_Settings  Menu  Utilities  Compilers  Test  Help
-----------------------------------------------------------------------------
EDIT     USER239.XMLIN(PACKSRCH) - 01.00                  Columns 00001 00072 
Command ===> _______________________________________________ Scroll ===> CSR 
****** **************************** Top of Data ******************************
000001 <?xml version="1.0"?>
000002 <service name="PACKAGE">
000003  <scope name="GENERAL">
000004   <message name="SEARCH">
000005    <header>
000006     <subsys>7</subsys>
000007     <test>T</test>
000008     <product>CMN</product>
000009    </header>
000010    <request>
000011     <package>                                               </package>
000012     <workChangeRequest>            </workChangeRequest>
000013     <requestorDept>    </requestorDept>
000014     <searchForSimpleLevel>  </searchForSimpleLevel>
000015     <searchForComplexLevel>  </searchForComplexLevel>
000016     <searchForSuperLevel>  </searchForSuperLevel>
000017     <searchForPartLevel>  </searchForPartLevel>
000018     <searchForPlannedPermType>  </searchForPlannedPermType>
000019     <searchForPlannedTempType>  </searchForPlannedTempType>

At the top of the XML document template, you will find the header information used to route your XML document to the correct ChangeMan ZMF instance for execution. The content shown in the XML <header> tags is the information you entered in Step 2: Select an XML Service. (For more information about Serena XML <header> tag syntax, see High-Level Tags in Serena XML.

Below the <header> tag block comes the <request> tag block. Opening and closing tag pairs appear on a single line. Between the opening and closing tags are blanks, which represent the maximum data length accepted by the tag. Each tag pair serves as a data entry prompt. XMLSERV assumes you already know what each tag means. Information about allowed data types, valid tag combinations, and the like appear earlier in this manual.

In this exercise, you will search for all packages in an application with package numbers starting in "0000". Do the following:

Change the <package> tag in the XML <request> block to read as follows:

<package>appl0000

Where appl is your application ID.

The request for this service allows entry of multiple package names delimited by semicolon, so you must scroll to the right to see the closing tag. You can leave the spaces between the end of your data and the closing tag, or you can eliminate the spaces.

Note

Be careful not to delete any of the lines after the tag when you edit your XML input document. These are the matching terminators for the opening XML tags at the top of the document.

Step 4: Execute the Edited XML Request

When you are satisfied with the contents of your XML input document, it’s time to execute your XML Services request. To do this:

  1. Type RUN at the ISPF command line or COMMAND ===> prompt.
  2. Press Enter.

XMLSERV saves the edits you made to your input document and passes it to SERXMLBC. SERXMLBC submits the request to the specified ChangeMan ZMF server, which validates your authority, and if ok, then executes the request and returns an XML reply to SERXMLBC. SERXMLBC saves the reply as an XML output document, then passes it back to XMLSERV. XMLSERV opens an ISPF session in which you can browse the returned XML.

Step 5: Browse the XML Output Document

XMLSERV starts an ISPF session to display your XML output document in view mode. The screen should look something like this:

File Edit Edit_Settings Menu Utilities Compilers Test Help
-----------------------------------------------------------------------------
VIEW       USER239.XMLOUT(PACKSRCH) - 01.00               Columns 00001 00072 
Command ===> _______________________________________________ Scroll ===> CSR 
****** **************************** Top of Data ******************************
000001 <?xml version="1.0"?>
000002 <service name="PACKAGE">
000003  <scope name="GENERAL">
000004   <message name="SEARCH">
000005     <result>
000006      <package>DEMO000019</package>
000007      <applName>DEMO</applName>
000008      <packageId>000019</packageId>
000009      <packageLevel>1</packageLevel>
000010      <packageType>1</packageType>
000011      <packageStatus>6</packageStatus>
000012      <requestorName>Agusto Yearwood</requestorName>
000013      <requestorPhone>808-393-6109</requestorPhone>
000014      <creator>USER239</creator>
000015      <tempChangeDuration>000</tempChangeDuration>
000016      <isStageLibDeleted>N</isStageLibDeleted>
000017      <isPackageLinked>N</isPackageLinked>
000018      <isCmnSchedulerUsed>N</isCmnSchedulerUsed>
000019      <isManualSchedulerUsed>Y</isManualSchedulerUsed>

Page down through the document with PF8. Each package that matches your search criteria appears in a <result> block. Nested within the opening <result> and closing

tag delimiters for the block, you will find XML subtags detailing the many items found in the package general record for matching packages. Multiple <result> blocks, one for each package found, may be returned in response to a package search request.

Following the final <result> block is the <response> block for this XML output document. The <response> block contains a return code and any status messages concerning the execution of your XML request. For a successful package search request, the <response> block looks like this:

<response>
<statusMessage>CMN8600I - The Package search list is complete.</statusMessage>
<statusReturnCode>00</statusReturnCode>
<statusReasonCode>8600</statusReasonCode>
</response>

Always check the <response> block to verify that your XML request executed successfully.

Because XMLSERV displays the XML output in ISPF view mode, you can use standard ISPF edit commands to review the data. This gives you a handy way to see a short list of all packages that satisfied your search criteria. Do this:

At the ISPF command line or Command ===> prompt, type the following instructions to filter the contents of the XML output document:

X ALL; F ALL <package>; HIDE X

ISPF shows the results as follows:

  File Edit Edit_Settings Menu Utilities Compilers Test Help
-----------------------------------------------------------------------------
VIEW      USER239.XMLOUT(PACKSRCH) - 01.00               72 CHARS '<PACKAGE>' 
Command ===> _______________________________________________ Scroll ===> CSR 
****** ***************************** Top of Data ****************************
000006      <package>DEMO000019</package>
000042      <package>DEMO000020</package>
000078      <package>DEMO000021</package>
000114      <package>DEMO000022</package>
000149      <package>DEMO000023</package>
000185      <package>DEMO000027</package>
000228      <package>DEMO000028</package>
000270      <package>DEMO000029</package>
000306      <package>DEMO000030</package>

Type the RESET command to show all the XML output data once again.

Step 6: Return to the XML Input Document and Exit

When you have finished viewing the XML output document, do the following to finish your XMLSERV session:

  1. Press PF3 to return to the XML input document.

    Notice that your request was saved by XMLSERV in condensed form, with null tags removed. Also, spaces before the closing </package> tag are deleted:

    File Edit Edit_Settings Menu Utilities Compilers Test Help
-----------------------------------------------------------------------------
EDIT    USER239.XMLIN(PACKSRCH) - 01.00                   Columns 00001 00072 
Command ===> _______________________________________________ Scroll ===> CSR 
****** **************************** Top of Data *****************************
000001 <?xml version="1.0"?>
000002 <service name="PACKAGE">
000003  <scope name="GENERAL">
000004   <message name="SEARCH">
000005    <header>
000006     <subsys>5</subsys>
000007     <product>CMN</product>
000008    </header>
000009    <request>
000010     <package>demo0000*</package>
000011    </request>
000012   </message>
000013  </scope>
000014 </service>
****** ************************** Bottom of Data ****************************

    ...

    Note

    If you think you might want to change an XMLSERV input document after it has been saved, you can keep null tags and trailing spaces by using this form of the RUN command: RUN NODROP

  2. Press PF3 to return to the XMLSERV main screen.

  3. To exit XMLSERV, press PF3 or type Exit at the ISPF command line or Command ===> prompt.