How this Works
This could be a direct connection to the application if the application is SOAP enabled. It does not have to be an intermediate connect except in the case of INFO/MAN as that reside on the mainframe and is not SOAP enabled.
The requirement for this interface to work is that the Information system must be available to handle HTTP Soap/XML calls and return Soap/XML data. It is the user's responsibility to maintain the Soap file for ZMF and a complete path to the Information System. You can have the Interface to INFO/MAN on a distributed platform. This system connects to INFO/MAN and gathers the data from INFO/MAN which is returned back to the distributed platform. The data gathered is then returned back to ZMF in a Soap/XML format. ZMF does not care where or what it is connecting to as long as it accepts HTTP Soap/XML calls. The connection can be directly to another product or an intermediate interface that handles the Soap/XML HTTP call.
From the ZMF point of view the HTTP Soap interface like the direct connection to INFO/ MAN and the INFO VSAM interface this interface is still a subtask of the main ZMF task. Also like the other INFO interfaces this interface functions the same as far as the data passed back and forth and the behaviors of ZMF are concerned. How this interface functions beyond that is totally different. The HTTP Soap interface reads the Soap File PDS member defined in administration and located in the PDS defined by the CMNINFO DD in the ZMF task startup procedure. A sample Soap definition file is provided later in this document. At startup time the INFO subtask gets the Soap file name defined in administration.
So, the INFO subtask must be detached and re-attached if a new Soap file name is defined. You can also cycle the main ZMF task for this. The Soap File determines the destination or endpoint as well as all the relationships between ZMF and the Information System. By relationships we mean as far as actions, ZMF variables and related XML tag names go. At a minimum the Soap file must contain the following statements at startup of the INFO subtask; XMLTAGS, ENDXMLTAGS, READREQ, ENDREAD, CREATEREQ ENDCREATE, UPDATEREQ and ENDUPDATE. Not required statements are PARENTREQ and ENDPARENT. If the READ, UPDATE and CREATE statements are found they must contain the ENDPOINT= statement.
When a request is processed by the INFO subtask it validates and requires that the following statements XMLTAGS and ENDXMLTAGS are present. The type of request determines the other required statements such as READREQ and ENDREAD are present. All request types also validate that the ENDPOINT= statement is present in the request. The ENDPOINT statement must start with http:// or it is considered invalid.
Basically, ZMF processes the request by reading the Soap file, placing ZMF INFO control block data into the SOAP, connecting to the endpoint and issuing the SOAP/XML request. Upon return the SOAP/XML data returned is processed and used to populate the ZMF INFO control block data. When the Soap file is read it looks for ZMF XML variables and replaces them with the actual data from the ZMF INFO control block. When processing the returned data ZMF looks for the assigned XML tags, when found the ZMF INFO control block is updated with the data returned by that tag name.
The ZMF XML variables and related XML tags are defined between the XMLTAGS and ENDXMLTAGS statements. The ZMF XML variables are 10 characters in length and assigned by Serena and relate to ZMF variables in the ZMF INFO control block. The related XML tag names are assigned by the customer and are a maximum of 120 characters. NEQERRTAG0-9 and EQUERRTAG0-9 also have values separated by a ';' up to 120 characters. The XML tags relate to the variable used in the customer product interface. ZMF reads the Soap file table and builds an internal table that contains this information. Most ZMF XML variables require the XML Tag Name to be a valid XML tag name containing the \< and > start and end of a tag name. The exceptions are XMLINFOID#, XMLNORECFD and XMLERRMSG0-9.
You may delete any of the variables you are not interested in, but must keep XMLINFOID# at a minimum. You can assign the same XML Tag Name to multiple ZMF XML variables. If you add your own ZMF XML variables or other data between the XMLTAGS and ENDXMLTAGS statements they will be ignored. Below is a table of available ZMF XML variables as they relate to the ZMF INFO control block and SOAP file table. The only time you would have to make sure that XMLINFOID# has an XML tag name is if you plan on using the create request. ZMF XMLPRNTID# has a special meaning as it will invoke the parent request process (PARENTREQ). The data returned for XMLPRNTID# is assumed to be a related change request number that contains information required that the original read request cannot return. If data is returned for XMLPRNTID# another read request is issued using the SOAP/XML contained in the PARENTREQ request. This is a never ending loop until there is no data for XMLPRNTID#. By this we mean if any of the read requests return back for the assigned XML Tag Name for XMLPRNTID# another PRNTREQ read request will be issued. If the assigned XML Tag Name for XMLPRNTID# is not present or contains no data then the read request ends .
XMLNORECFD is a string to look for in the returned data that means the record requested was not found. This could be an XML tag or anything else up to 120 characters. This differs from other errors as everything worked but the record requested was not found. XMLERRMSG0-9 are a string to look for in the returned data that means there was some sort of error other than record not found. XMLERRMSG0-9 can also be a valid XML tag. The data from this tag if found is placed in the message for ZMF and constitutes an error. NEQERRTAG0-9 and EQUERRTAG0-9 have a special meaning and do require a valid XML tag name followed by some data values. The NEQERRTAG0-9 variables validate that any value returned for the specified XML tag name is an error if not equal to one of the specified values. The EQUERRTAG variables validate that any value that is returned for the specified XML tag name is an error if equal to one of the specified values.
NEQERRTAG0-9 and EQUERRTAG0-9 format:
NEQERRTAGn <tag_name\> value;value;value;…….. (where n is the number 0-9)
Below is a table of ZMF XML variables and the XML tag names. You can remove any of the ZMF variables you are not using. When this table is loaded into internal memory any variables with no associated tag name or value, it then will not be loaded into the internal memory table. You can assign the same tag name to different ZMF XML variables. You can also assign different XML tag names to the same ZMF variable by repeating the ZMF variable. However, the first ZMF variable in the table will take the highest priority over the repeated ZMF variable. If the ZMF variable has nothing returned for it then the next occurrence that has data returned for it will then be used.
| ZMF XML Variable | INFO Block Variable | XML Tag Name | Description | |
|---|---|---|---|---|
| XMLINFOID# | INF$CHGN | <user_defined> | Change Number/Work Request number | |
| XMLAPPRSTA | INF$APRV | <user_defined> | INFO Approval Status | |
| XMLPACKAGE | INF$PKGN | <user_defined> | Package Name | |
| XMLPKGSTAT | INF$STAT | <user_defined> | Package Status | |
| XMLPKGDESC | INF$STIT | <user_defined> | Package Description | |
| XMLPKGTYPE | INF$TPKG | <user_defined> | Package Type | |
| XMLPKGLEVL | INF$LPKG | <user_defined> | Package Level | |
| XMLREQNAME | INF$CNAM | <user_defined> | Requestor Name | |
| XMLREQPHON | INF$CPHN | <user_defined> | Requestor Phone | |
| XMLDEPART# | INF$DEPT | <user_defined> | Department | |
| XMLPKGCRTN | INF$CTSO | <user_defined> | Package Creator TSOID | |
| XMLINSDATE | INF$IDAT | <user_defined> | Default Install Date | |
| XMLINSFTME | INF$IFTM | <user_defined> | Default Install From Time | |
| XMLINSTTME | INF$ITTM | <user_defined> | Default Install To Time | |
| XMLRLSNAME | INF$RLSN | <user_defined> | Package Release Name | |
| XMLARENAME | INF$RARE | <user_defined> | Package Release Area | |
| XMLRMTSITE | INF$SITE | <user_defined> | Remote Site Name | |
| XMLPRMNAME | INF$CNM1 | <user_defined> | Primary Contact Name | |
| XMLPRMPHON | INF$CPH1 | <user_defined> | Primary Contact Phone | |
| XMLSCDNAME | INF$CNM2 | <user_defined> | Secondary Contact Name | |
| XMLSCDPHON | INF$CPH2 | <user_defined> | Secondary Contact Phone | |
| XMLPRNTID# | N/A | <user_defined> | Related INFO Change Number | |
| XMLNORECFD | N/A | User defined | Record Not Found Value | |
| XMLERRMSG0 | N/A | User defined | Error Message Value | |
| XMLERRMSG1 | N/A | User defined | Error Message Value | |
| XMLERRMSG2 | N/A | User defined | Error Message Value | |
| XMLERRMSG3 | N/A | User defined | Error Message Value | |
| XMLERRMSG4 | N/A | User defined | Error Message Value | |
| XMLERRMSG5 | N/A | User defined | Error Message Value | |
| XMLERRMSG6 | N/A | User defined | Error Message Value | |
| XMLERRMSG7 | N/A | User defined | Error Message Value | |
| XMLERRMSG8 | N/A | User defined | Error Message Value | |
| XMLERRMSG9 | N/A | User defined | Error Message Value | |
| NEQERRTAG0 | N/A | <user_defined> | ChangeMan LPAR | |
| NEQERRTAG1 | N/A | <user_defined> | Activity Change Type | |
| NEQERRTAG2 | N/A | <user_defined> | NE Error | |
| NEQERRTAG3 | N/A | <user_defined> | NE Error | |
| NEQERRTAG4 | N/A | <user_defined> | NE Error | |
| NEQERRTAG5 | N/A | <user_defined> | NE Error | |
| NEQERRTAG6 | N/A | <user_defined> | NE Error | |
| NEQERRTAG7 | N/A | <user_defined> | NE Error | |
| NEQERRTAG8 | N/A | <user_defined> | NE Error | |
| NEQERRTAG8 | N/A | <user_defined> | NE Error | |
| EQUERRTAG0 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG1 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG2 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG3 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG4 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG5 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG6 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG7 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG8 | N/A | <user_defined> | EQ Error | |
| EQUERRTAG9 | N/A | <user_defined> | EQ Error |
All the request statements must be in the Soap file. These include the read request (READREQ and ENDREAD), the update request (UPDATEREQ and ENDUPDATE), the create request (CREATEREQ and ENDCREATE). Each of these requests must contain and ENDPOINT= statement and the endpoint must start with http:// or it is considered invalid. The ENDPOINT statement should be the first statement in the request. All statements prior to the ENDPOINT statement are ignored. If you do not want to use a request type it must still exist as well as the ENDPOINT statement. See below for a sample of a request type you do not want to use. Do not have any SOAP/XML entered for a request type you do not want to use. ZMF will consider the request successfully executed.
CREATEREQ:
ENDPOINT=http://no call for this request
ENDCREATE:
If your product interface requires a SOAPAction the SOAPAction= statement must be on the line immediately following the ENDPOINT= statement. If your product interface requires a Method Name the Method= statement must be on the line immediately following the SOAPAction=statement if there. Otherwise the Method= statement must be on the line immediately following the ENDPOINT= statement. If there is no SOAPAction= or Method= statements then everything following the ENDPOINT= statement is considered SOAP/XML until the END of the request statement is reached. If there is a SOAPAction= statement and/or a Method= statement, then everything following the SOAPAction= statement and/or the Method= statement is considered SOAP/XML until the END of the request statement is reached.
Everything between the start of the request statement (i.e. READREQ) and the ENDPOINT statement is ignored. This is a good place to put comments if desired.
When using only one install time for your information system you can place that in either the install to or from time. If placed in the from install time, the to install time is incremented by one minute. If placed in the to install time, the from install time is decremented by one minute.