z/OS Connect-Services definieren
z/OS® Connect-Servicedefinitionen stellen den Mechanismus für das Erreichen von z/OS-Anwendungsassets über REST-Aufrufe bereit. Zum Aktivieren von z/OS Connect-Services müssen Sie der Libertydatei server.xml eine z/OS Connect-Servicedefinition mit dem Elementnamen zosConnectService und einem Namen sowie einem Service-Provider-Referenzelementnamen hinzufügen.
Informationen zu diesem Vorgang
z/OS Connect-Services werden vom Konfigurationselement zosConnectService definiert. Dieses Element enthält Attributdefinitionen, die global definierte Entsprechungen haben können. Attribute können global mit dem Element zosConnectManager definiert werden. Diese Attribute gelten (sofern angegeben) für alle Services. Wenn die globalen Attribute und die Attribute auf Serviceebene konfiguriert sind, werden die auf der Ebene zosConnectService verwendeten Werte verwendet.
z/OS Connect stellt eine Serviceimplementierung bereit, die ermöglicht, dass z/OS Connect-Anforderungen über WebSphere Optimized Local Adapters (WOLA) mit z/OS-Assets interagieren. Der Service wird automatisch aktiviert, wenn die Features zosConnect-1.0 und zosLocalAdapters-1.0 konfiguriert werden. Instanzen dieses Service können über das Konfigurationselement localAdaptersConnectService definiert werden.
z/OS Connect stellt auch eine Serviceimplementierung bereit, die ermöglicht, dass z/OS Connect-Anforderungen ferne REST-Endpunkte kontaktieren. Der Service ist verfügbar, wenn das Feature zosConnect-1.2 konfiguriert ist. Instanzen dieses Service können über das Konfigurationselement zosConnectServiceRestClient definiert werden. Weitere Informationen finden Sie in der Dokumentation unter z/OS Connect-REST-Client-Service.
Vorgehensweise
- Fügen Sie für jeden Service in Ihrer Konfigurationsdatei server.xml ein Konfigurationselement zosConnectService
hinzu. Sie müssen mindestens die Attribute "serviceRef" und "serviceName"
konfigurieren. Das Element "serviceRef" verweist auf das Konfigurationselement des Service-Providers.
Das Attribut "serviceName" beschreibt, wie der Service-Provider sich selbst
bei z/OS Connect angibt, und ist außerdem der Name,
der als Teil der URL für z/OS Connect-Anforderungen verwendet werden soll, die auf einen bestimmten Service
abzielen. Der Servicename muss eindeutig sein. Im Folgenden sehen Sie eine Beispieldatei vom Typ server.xml, die zeigt, welche Elemente einem
z/OS Connect-Service mit dem Namen "recordOpsCreate" hinzugefügt werden müssen. In Schritt 3 wird ein umfassenderes Beispiel angezeigt.
Weitere Informationen zu den konfigurierbaren Attributdefinitionen, die dem Element zosConnectService zugeordnet sind, finden Sie in der Dokumentation zum Feature z/OS Connect.<!-- z/OS Connect-Servicedefinitionen --> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate"/>
- (Optional) Fügen Sie der Datei server.xml das Konfigurationselement zosConnectManager
hinzu.
Dieses Element ist ein Singleton in der Konfigurationsdatei server.xml und enthält globale Werte, die für alle z/OS Connect-Services gelten, die für den Server definiert sind. Das Element kann die Namen von z/OS Connect-Interceptors oder Konfigurationselemente für den Datentransformationsprovider enthalten, die für alle Services im Server gelten.
Das folgende Beispiel beschreibt das Konfigurationselement zosConnectManager, das den Operationsgruppennamen "Operator1" unter dem Element "globalOperationsGroup" definiert. Dies ist der Name der Sicherheitsgruppe (SAF oder LDAP), zu der die Benutzer-ID des anfordernden Clients gehören muss, damit z/OS Connect-Operationsanforderungen zulässig sind, z. B. action=start|stop|status. Diese Gruppe gilt für alle Services in den z/OS Connect-Konfigurationen. Das Element "dataxform" definiert den Elementnamen, unter dem z/OS Connect einen Datentransformationsprovider finden kann. Wird dataxform im Element "zosConnect" angegeben, bedeutet das, dass dies die Transformationsproviderimplementierung für alle Services in der Konfiguration ist, die noch keinen eigenen Elementverweis für die Datentransformation haben. Das Interceptorelement ist der Name des Elements in der Konfiguration, das den Satz von z/OS Connect-Interceptors beschreibt, die für alle Services in der Konfiguration gelten.
<zosConnectManager id="zosConnectGlobals" globalOperationsGroup="Operator1" globalDataxformRef="XformJSON2Byte" globalInterceptorsRef="GlobalInterceptors"/>
Weitere Informationen zu den konfigurierbaren Attributdefinitionen, die dem Element zosConnectManager zugeordnet sind, finden Sie in der Dokumentation zum Feature z/OS Connect.
Weitere Informationen zu jedem Attribut finden Sie in der Dokumentation zu den Features von Liberty. - Wenn WOLA in Liberty konfiguriert ist, setzt die Konfiguration für einen Anforderung
das Konfigurationselement localAdaptersConnectService
in der Datei server.xml voraus. Diese Konfiguration besteht mindestens aus dem
Zielnamen der WOLA-Verbindungsfactory, dem Registrierungsnamen und dem Servicenamen.
Die Konfiguration von z/OS Connect folgt den Liberty-Konventionen, d. h., es müssen nur die Mindestparameter
angegeben werden. Beachten Sie, dass Sie bei der Konfiguration einer WOLA-Verbindungsfactory
für die z/OS Connect-Interaktion einen Container als Authentifizierungsmechanismus verwenden müssen. WOLA-Verbindungsfactorys, die kein
containerAuthDataRef-Attribut angeben, werden nicht unterstützt.
Beispiel:
<!-- Definition der Verbindungsfactory für lokale Adapter --> <authData id="cauth1" user="user1" password="{xor}LDo8Ki02KyY="/> <connectionFactory id="wolaCF" jndiName="eis/ola" containerAuthDataRef="cauth1" > <properties.ola/> </connectionFactory> <!-- Konfiguration für lokale Adapter --> <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="LIBERTY" wolaName3="LIBERTY" /> <!-- WOLA-Verbindungsservice und z/OS Connect-Servicedefinitionen --> <localAdaptersConnectService id="wolaOpsCreate" registerName="BATCH01" serviceName="COBLPGM1" connectionFactoryRef="wolaCF"/> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate" runGlobalInterceptors="true" interceptorsRef="serviceInterceptorList" dataXformRef="zconXform"/> <!-- z/OS Connect-Datentransformer --> <zosConnectDataXform id="zconXform" bindFileLoc="/zosConnect/bind" bindFileSuffix=".bnd" requestSchemaLoc="/zosConnect/schema" responseSchemaLoc="/zosConnect/schema" requestSchemaSuffix=".json" responseSchemaSuffix=".json"> </zosConnectDataXform>
Die z/OS Connect-Serviceimplementierung, die ermöglicht, dass z/OS Connect-Anforderungen mit z/OS-Assets über WebSphere Optimized Local Adapters (WOLA) interagieren, erfordern möglicherweise einen Datentransformer. Wenn ein Datentransformer konfiguriert ist (global oder auf Serviceebene), werden Eingabe- und Ausgabenutzdaten mit dem konfigurierten Datentransformer konvertiert. Wenn kein Datentransformer konfiguriert ist und die Anforderung JSON-Nutzdaten enthält, geht der Service davon aus, dass das Ausgabeprogramm die Datenkonvertierung vornimmt. Der Service konvertiert die JSON-Nutzdaten unverändert in ein Byte-Array und verwendet dafür die im Anforderungsheader angegebene Verschlüsselung oder die JSON-Standardverschlüsselung "UTF-8". Wenn das Asset Nutzdaten zurückgibt und kein Datentransformer konfiguriert ist, erwartet die WOLA-Serviceimplementierung den Empfang von JSON-Nutzdaten als Byte-Array, das denselben Verschlüsselungsregeln folgend, die auch für die Transformation von JSON-Anforderungsnutzdaten in ein Byte-Array verwendet werden, in JSON-Antwortnutzdaten konvertiert wird.
Wenn linkTaskChanID zusammen mit der Angabe useCICSContainer=true unter dem Element localAdaptersConnectService konfiguriert ist, wird eine Gruppe von Kontextcontainern und Nutzdatencontainern an das Zielprogramm gesendet. Die folgende Liste enthält die Namen und Beschreibungen der Kontextcontainer.- ZCONReqURL
- Der Kontextcontainer ZCONRegURL enthält die HTTP-Anforderungs-URL. Wenn Sie beispielsweise eine invokeURI-Definition mit /banking/deposit und dem Abfrageparameter country=USA verwenden, lautet die URL wie folgt: https//localhost:port/banking/deposit?country=USA.
- ZCONReqQParms
- Der Kontextcontainer ZCONReqQParms enthält die HTTP-Anforderungsabfrageparameter. Bei der Anforderungs-URL https//localhost:port//banking/deposit?country=USA ist der Abfrageparameter country=USA.
- ZCONReqMethod
- Der Kontextcontainer ZCONReqMethod enthält die HTTP-Anforderungsmethode. Beispiel: GET.
- ZCONHTTPHeaders
- Der Kontextcontainer ZCONHTTPHeaders enthält eine Gruppe von HTTP-Header-Name/Wert-Paaren in JSON-Formatierung, die unter Verwendung des Attributs linkTaskChanCtxContHttpHeaders unter dem Element localAdaptersConnectService konfiguriert wurden.
Benutzer können die Standardcodierung der Daten (cp819), die in allen Kontextcontainern vorhanden ist, über das Konfigurationsattribut linkTaskChanCtxContEncoding unter dem Element localAdaptersConnectService ändern.
Wenn linkTaskChanID zusammen mit der Angabe useCICSContainer=true unter dem Element localAdaptersConnectService konfiguriert ist, können Sie die Nutzdatennamen der Eingabe- und Ausgabecontainer über die Attribute linkTaskChanReqContID und linkTaskChanRespContID anpassen. Wenn diese Attribut nicht definiert sind, lauten die Standardnamen ZCONReqData und ZCONRespData. Das folgende Beispiel veranschaulicht eine ordnungsgemäß Konfiguration.<localAdaptersConnectService id="wolaOpsCreate" registerName="OLASERVER" serviceName="ZCONMC5" connectionFactoryRef="wolaCF" linkTaskChanID="ZCONCHANNEL" linkTaskChanType="1" useCICSContainer="true" linkTaskChanCtxContHttpHeaders="Connection, CustomHeader1, CustomHeader2, CustomHeader3" linkTaskChanReqContID="wolaOpsReqData" linkTaskChanRespContID="wolaOpsRespData" linkTaskChanCtxContEncoding="cp037"/>
Die folgende Tabelle ist eine Liste mit localAdaptersConnectService-Attributdefinitionen und jeweils einer zugehörigen Beschreibung.
Attributdefinition Beschreibung serviceName
required="true"
type="String"
Name des WOLA-Zielservice. serviceName muss mit dem Namen übereinstimmen, den eine externe Adressraumanwendung als Servicenamen bei einem WOLA-Aufruf der API "Receive Request" oder "Host Service" verwendet, oder mit dem Namen, der für SVC mit einem WOLA-CICS-Link-Server verwendet wird. registerName
required="true"
type="String"
Der Name der WOLA-Zielregistrierung. Dieser Name muss mit dem Namen übereinstimmen, den eine externe Adressraumanwendung als Registrierungsnamen bei einem WOLA-Aufruf der API "Register" verwendet, oder mit dem Namen, der für RGN mit einem WOLA-CICS-Link-Server verwendet wird. registerName kann eine beliebige aus 1 bis 12 Zeichen bestehende alphanumerische Zeichenfolge sein. connectionFactoryRef
required="true"
type="String"
Referenziert die konfigurierte WOLA-Ressourcenadapter-Verbindungsfactory. connectionWaitTimeout
required="false"
type="Integer"
min="0"
max="2147483647"
Die Zeit (in Sekunden), die auf eine externe Adressraumanwendung gewartet wird, die mit dem Registrierungsnamen zum Absetzen und Aktivieren eines WOLA-Aufrufs der API "Receive Request" oder "Host Service" verwendet wird. Dieses Attribut definiert die Eigenschaft ConnectionWaitTimeout in der OLA-Verbindungsfactory (Optimized Local Adapter). Wenn kein Wert angegeben wird, wird der Standardwert der Eigenschaft verwendet. Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskTranID
required="false"
type="String"
Definiert den Namen der Transaktions-ID für die Linkaufruftask des WOLA-CICS-Link-Servers (eine beliebige aus vier Zeichen bestehende Zeichenfolge). Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird. Dieses Attribut definiert die Eigenschaft LinkTaskTranID in der OLA-Verbindungsfactory (Optimized Local Adapter). Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. useCICSContainer
required="false"
type="Boolean"
default="false"
Definiert den für die Datenweitergabe zu verwendenden Mechanismus. Wenn diese Eigenschaft auf "true" gesetzt ist, werden die Nutzdaten über CICS-Container an das CICS-Zielanwendungsprogramm übergeben. Wenn diese Eigenschaft auf "false" gesetzt ist, werden die Nutzdaten über einen Kommunikationsbereich (COMMAREA) an das CICS-Zielanwendungsprogramm übergeben. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird. Dieses Attribut definiert die Eigenschaft useCICSContainer in der OLA-Verbindungsfactory (Optimized Local Adapter). Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskReqContType
type="Integer"
min="0"
default="0"
Definiert den Typ des Anforderungscontainers (0=CHAR, 1=BIT). Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskReqContID" und "useCICSContainer" mit "true" konfiguriert sind. Dieses Attribut definiert die Eigenschaft "linkTaskReqContType" in der OLA-Verbindungsfactory. Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskRspContID
required="false"
type="String"
Definiert den Namen des Antwort- bzw. Ausgabecontainers. Eine aus 1 bis 16 Zeichen bestehende Zeichenfolge, die dem in CICS definierten Containernamen entspricht. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskReqContID" und "useCICSContainer" mit "true" konfiguriert sind. Dieses Attribut definiert die Eigenschaft LinkTaskTranID in der OLA-Verbindungsfactory (Optimized Local Adapter). Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskRspContType
type="Integer"
min="0"
default="0"
Definiert den Typ des Antwortcontainers (0=CHAR, 1=BIT). Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskRspContID" und "useCICSContainer" mit "true" konfiguriert sind. Dieses Attribut definiert die Eigenschaft "linkTaskRspContType" in der OLA-Verbindungsfactory. Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskChanID
required="false"
type="String"
Definiert den Namen des CICS-Kanals, der für die Zustellung und den Empfang von Nutzdaten über CICS-Container verwendet werden soll mit einer aus 1 bis 16 Zeichen bestehenden Zeichenfolge, die dem in CICS definierten Containernamen entspricht. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn das Attribut "useCICSContainer" mit "true" konfiguriert ist. Dieses Attribut definiert die Eigenschaft "linkTaskChanID" in der OLA-Verbindungsfactory. Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskChanType
required="false"
type="Integer"
min="0"
default="0"
Definiert den Typ der CICS-Container (0=CHAR, 1=BIT), die der konfigurierten Kanal-ID zugeordnet werden sollen. Wenn diese Eigenschaft auf 0=CHAR (Standardeinstellung) gesetzt ist, werden die Zeichendaten in den Eingabe-/Ausgabecontainern in ASCII-Codierung (CCSID 819) erwartet und zurückgegeben und die Daten werden in bzw. aus EBCDIC (cp037) konvertiert, bevor bzw. nachdem sie an das bzw. vom Zielprogramm gesendet werden. Verwenden Sie den Typ BIT, um Datentyp- und Codierungserwartungen zu vermeiden. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskChanID" und "useCICSContainer" mit "true" konfiguriert sind. Dieses Attribut definiert die Eigenschaft "linkTaskChanType" in der OLA-Verbindungsfactory. Weitere Informationen finden Sie unter "Verbindungsfactory-Eigenschaften für optimierte lokale Adpater" in der Liberty-Dokumentation. linkTaskChanReqContID
required="false"
default="ZCONReqData"
type="String"
Definiert den Namen des Anforderungscontainers mit einer aus 1 bis 16 Zeichen bestehenden Zeichenfolge, die dem in CICS definierten Containernamen entspricht. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskChanID" und "useCICSContainer" mit "true" konfiguriert sind.
linkTaskChanRespContID
required="false"
default="ZCONRespData"
type="String"
Definiert den Namen des Antwortcontainers mit einer aus 1 bis 16 Zeichen bestehenden Zeichenfolge, die dem in CICS definierten Containernamen entspricht. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskChanID" und "useCICSContainer" mit "true" konfiguriert sind.
linkTaskChanCtxContEncoding
required="false"
type="String"
default="cp819"
Definiert die Codierung der Daten in allen Kontextcontainern, die an das Zielprogramm gesendet werden. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskChanID" und "useCICSContainer" mit "true" konfiguriert sind.
linkTaskChanCtxContHttpHeaders
required="false"
type="String"
Definiert den HTTP-Headernamen bzw. eine durch Kommas getrennte Liste mit Headernamen, der bzw. die über den Kontextcontainer mit dem Namen "ZCONHTTPHeaders" an das Zielprogramm übergeben wird. Die in diesem Kontextcontainer enthaltenen Informationen haben das folgende JSON-Format: {httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}}. Dieses Attribut wird verwendet, wenn der CICS-Link-Server verwendet wird und wenn die Attribute "linkTaskChanID" und "useCICSContainer" mit "true" konfiguriert sind.


Dateiname: twlp_zconnect_srvcdef.html