XMLSERV Functional Overview

When you first start XMLSERV, it displays a list of the user’s available XML functions on the main screen. The specific subsystem selected must be running.

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

The main screen lists valid Serena XML functions in alphabetical order by service name. Names in the Service, Scope, and Message columns correspond to the name attributes for the Serena XML <service>, <scope>, and <message> tags, respectively. Only valid combinations are shown.

The Color column flags each service with the level of caution recommended for its use:

Color	Meaning
G (Green)	Equivalent to an ISPF interface function in most cases. No special training is required prior to use.
Y (Yellow)	Implements a low-level subset of an ISPF function without checks. **Caution must be exercised to prevent database integrity issues.

...

Note

Security protection can be set up to prevent access to any and all services. Any that the user does not have access to will not be displayed in XMLSERV.

The Copybook column provides the stem name of the copybook used with each service.

These names can be combined with the service color to determine the names of the sample COBOL-to-XML copybooks to be used with SERXMLCC. Sample COBOL copybooks are prefixed with XMLC for green services and XMLY for yellow services. For example, the copybook for the APPROVER.APL.LIST service would be XMLCAAPR. Copybooks are delivered in the SERCOMC ASMCPY library unloaded from the ChangeMan ZMF installer.

Use the PF8 key to page through the list and find the function you want. Type an "S" beside the function to select it. When you select a function, XMLSERV supplies all the valid XML subtag names for the corresponding <request> message. The displayed tag names serve as data entry prompts. After entering the data needed for your request, submit the XML request to ChangeMan ZMF directly from XMLSERV. ChangeMan ZMF executes the request and returns an XML reply. XMLSERV displays the <reply> message in XML format online.

The XMLSERV main screen provides menu-driven shortcuts to frequently performed tasks. These appear under the File and Help menus.

File Menu
	Open	Opens an existing XML input document for editing in XMLSERV. You will be offered a list of the members in the input dataset.
	Exit	Exit from XMLSERV.

Help Menu
	Help	Provides online information about how to use XMLSERV.
	Keys Help	Displays PF key definitions for use with XMLSERV.
	About	Gives release-level information about XMLSERV.

...

Main Screen Primary Commands

XMLSERV supports the following primary commands at the main screen to facilitate its use.

ABOUT Command

The About command displays the 'About' panel, which includes the XML DSECT create date.

Syntax:

ABOUT

FILTER Command

The Filter command filters the list of XML functions to show only entries matching the specified criteria. Parameters are positional but optional. Parameter values may be masked with a trailing asterisk (*) wild card character.

Syntax:
`FILTER (service\|) (scope\|) (message\|) (color\|) (copybook\|*)`

Examples:
FILTER SITE	Lists all functions with the service name SITE.
FILTER `* ` UNFR``	Lists all functions with a message name beginning in ‘UNFR’, such as UNFREEZE.
FILTER PACKAGE `* *` Y	Lists all Yellow functions with the service name PACKAGE.
FILTER	Lists all functions for all services. (Default)

The FILTER command uses the ISPF TBSARG service, which locates the scroll position as close to its original position as possible. If you issue a second FILTER command without first restoring the complete list (FILTER command with no parameters) and moving to the top of the list, you may need to scroll up to see the new results.

FIND Command

The Find command finds the next entry that contains a specified string in the service, scope or message name. No masking is available for the search string. If no search string is specified, the previous Find command is repeated.

Syntax:
`FIND string`

Examples:
FIND HIST	Finds the next XML function with a service, scope, or message name containing the string ‘HIST’.
FIND	Repeats the previous Find command. (Default)

LOCATE Command

The Locate command finds the next entry that matches the specified criteria for one or more parameters. Parameters are positional but optional. Parameter values may be masked with a trailing asterisk (*) wild card character. If no parameters are specified, the previous Locate command is repeated.

Syntax:
`LOCATE (service\|) (scope\|) (message\|) (color\|) (copybook\|*)`

*Examples:
LOCATE SITE	Finds the next function with the service name SITE.
LOCATE `* ` UNFR``	Finds the next function with a message name beginning in ‘UNFR’, such as UNFREEZE.
LOCATE	Repeats the previous Locate command. (Default)

LPRINT Command

The LPRINT command prints the currently displayed list of XML services to DDNAME XMLPRINT. By default, XMLPRINT is allocated to SYSOUT.

Syntax:
`LPRINT`

OPEN Command

The Open command opens the named member in the XML input dataset for editing with XMLSERV. If no member name is specified, the member list for the dataset is displayed.

Syntax:
`OPEN (member)`

RUN Command

The Run command submits the edited XML member to ChangeMan ZMF for execution.

By default, consecutive blanks in strings are collapsed to a single blank (in compliance with the XML standard) and blank tag entries are dropped before transmission over the network. However, if you wish preserve tag indentation or if blank tag values are intended for submission to ZMF and should not be dropped, use the optional NODROP parameter.

Syntax:
`RUN [NODROP]`

Examples:
RUN	Submits the currently open XML file to ZMF for execution. All blank tags are dropped and consecutive blanks in strings are compressed to single blanks before submission. (Default)
RUN NODROP	Submits the currently open XML file to ZMF for execution. All blanks are preserved.

SORT Command

The Sort command sorts the list of XML services by column name or column number. The first column in the parameter list identifies the outermost level of the sort. The last column in the parameter list identifies the innermost level of the sort. If no parameters are supplied, the sort is performed by service name, then scope within service, then message within scope.

Syntax:
`SORT (column_1) (column_2) ... (column_n)`

Examples:
SORT SCOPE	Sorts function list by scope name.
SORT MESSAGE SERVICE	Sorts function list by message name, then service name within message.
SORT 3 1	Equivalent to ‘SORT MESSAGE SERVICE’.
SORT	Sorts function list by service name, then scope name within service, then message name within scope. (Default)

XML Input and Output Documents

For each XML request and response document in your session, XMLSERV creates a new dataset member in a PDS library. Your administrator sets up the input and output PDS names and dataset allocations when installing XMLSERV. These datasets are passed to SERXMLBC for execution, so they should be allocated using SERXMLBC specifications. (See SERXMLBC – Executing Native XML Service Calls for dataset allocation recommendations. See the ChangeMan ZMF Installation Guide for information about installing XMLSERV.)

Within the input and output libraries, you can create multiple input and output members. Each member contains the XML input request and the XML output result for a single request/ response cycle. Input and output members for the same request/response cycle share the same member name. You can choose a different member name for each of several input/ output cycles.

For example, let’s say your input library is named userid.XMLIN and your output library is named userid.XMLOUT. You perform two tasks in a single XMLSERV session. The first task is a package search, so you assign the member name "PACKSRCH" to these input and output XML documents in XMLSERV. The second task is a component search, so you name its input and output document members "COMPSRCH" in XMLSERV. The resulting data set names at the end of your XMLSERV session would then be:

XML Input Documents	XML Output Documents
USER239.XMLIN(PACKSRCH)	USER239.XMLOUT(PACKSRCH)
USER239.XMLIN(COMPSRCH)	USER239.XMLOUT(COMPSRCH)

Because the input and output data sets are saved between XMLSERV sessions, you can reuse your XML request files either with XMLSERV or directly with the SERXMLBC client. Similarly, XML reply files can serve (after file format conversion from EBCDIC to ASCII) as input to XML-savvy reporting tools on the desktop.

Usage Notes

XMLSERV is a prototyping tool. It is provided as-is as an aid to systems integrators already familiar with the internals of ChangeMan ZMF. As such, it does not incorporate the fail-safes and self-checking you might expect to see in a general-purpose utility for end users. Micro Focus recommends that its use be limited to ChangeMan ZMF administrators and systems programmers only, and that use be controlled by your security system.