התקנת Mainframe Connector במחשב המרכזי

‫Mainframe Connector מופעל כתהליך של מכונה וירטואלית של Java‏ (JVM) בהקשר של משימת אצווה של MVS. בדרך כלל, פורסים את Mainframe Connector באמצעות קובץ JAR שמכיל כמה יחסי תלות נדרשים, מלבד ספריות IBM שכלולות ב-JVM. בקטעים הבאים מתואר תהליך ההתקנה של Mainframe Connector בפירוט.

לפני שמתחילים

  • משלימים את ההגדרה הראשונית של Mainframe Connector. ההגדרה הראשונית כוללת הקצאת התפקידים הנדרשים לחשבון השירות, הגדרת אבטחה לנכסים והגדרת קישוריות לרשת בין המחשב המרכזי לבין Google Cloud.
  • מגדירים את Java 8 או את Java 17.
  • מתקינים את JZOS Batch Launcher ואת Toolkit ‏ (Java 8 או Java 17).

התקנה של Mainframe Connector

כדי להתקין את Mainframe Connector:

  1. מורידים את קובץ ה-JAR של Mainframe Connector שנבנה מראש לספרייה שלחשבון המשתמש שלכם יש הרשאות כתיבה.

    חשוב

    חשוב לדעת ש-Mainframe Connector משתמש ב-Google Analytics כדי לאסוף נתוני שימוש. כך אנחנו יכולים לשפר את התוכנה ולספק חוויית משתמש טובה יותר. כברירת מחדל, Google Analytics מופעל. עם זאת, אתם יכולים לבטל את ההסכמה על ידי הגדרת משתנה סביבה כשמריצים את Mainframe Connector.

    השימוש ב-Google Analytics כפוף לתנאים ולהגבלות ולמדיניות הפרטיות של Google Analytics. הורדת Mainframe Connector פירושה אישור שקראתם והבנתם את התנאים וההגבלות והסכמתם להם.

    הורדה ביטול

  2. מעתיקים את הקובץ mainframe-connector-shadow-VERSION-all.jar לנתיב שצוין בקטע Java Classpath של הפרוצדורה job control language (JCL) של BQSH שמוצגת בשלב 8. ‫VERSION היא הגרסה של Mainframe Connector.

  3. כדי לגשת לשירותי Google Cloud ממחשב מרכזי, צריך ליצור ולהוריד מפתח של חשבון שירות כקובץ מפתח JSON. מידע נוסף על יצירת קובץ מפתח JSON זמין במאמר יצירת מפתח לחשבון שירות.

  4. מעתיקים את קובץ מפתח ה-JSON למערכת הקבצים של Unix באמצעות פרוטוקול העברת קבצים (FTP) במצב העברה בינארי. חשוב לוודא שקובץ מפתח ה-JSON המקורי מאוחסן במערכת הקבצים בקידוד UTF-8 המקורי שלו.

    אין נתיב ברירת מחדל לאחסון קובץ מפתח ה-JSON במערכת הקבצים של IBM z/OS Unix. צריך לבחור נתיב שרק משתמשים עם הרשאות גישה לחשבון השירות יכולים לקרוא. אם קובץ מפתח ה-JSON הועבר בצורה תקינה, לא תהיה אפשרות לקרוא אותו מ-UNIX System Services ‏ (USS).

  5. משתמשים ב-FTP במצב בינארי כדי להעלות את קובץ ה-JAR שהורדתם בשלב 1 למיקום הבא במחשב המרכזי.

     /opt/google/mainframe-connector/VERSION/

    מחליפים את Version בגרסה של קובץ ה-JAR.

    שימו לב: זו הדרך המומלצת לפריסת קובץ ה-JAR. אפשר גם להשתמש בכל נתיב שנבחר על ידי אדמין האתר.

  6. מריצים את הפקודה הבאה כדי לוודא שקובץ ה-JAR הועבר בצורה תקינה. שימו לב: האפשרות -t מציגה את התוכן של קובץ ה-JAR.

     jar -tvf JAR_FILE_NAME

    מחליפים את JAR_FILE_NAME בשם של קובץ ה-JAR.

  7. מעתיקים את הפרוצדורה הבאה של BQSH JCL ומחליפים את המשתנים הבאים.

    בפרוצדורה BQSH JCL, הערך BQSH_ROOT_LOGGER=DEBUG מציין שהופעלה יצירת יומן ניפוי באגים. כדי להשבית את הרישום ביומן לניפוי הבאגים, מוסיפים הערה לשורה או מגדירים את המשתנה לכל ערך אחר מלבד DEBUG.

    כדי להגדיר את Mainframe Connector כך שיכתוב מידע רישום ביומן ל-Cloud Logging, מגדירים את משתני הסביבה LOG_PROJECT ו-LOG_ID כמו בדוגמה הבאה.

    רשימה מלאה של משתני הסביבה שנתמכים על ידי Mainframe Connector מופיעה במאמר משתני סביבה.

    • ‫GKEY_FILE_PATH בנתיב לקובץ מפתח ה-JSON שמתואר בשלב 3.
    • ‫JAR_FILE_PATH בנתיב לספרייה שמכילה את קובץ ה-JAR.
    • ‫PROJECT_NAME עם הפרויקט שעבורו נוצר היומן ב-Cloud Logging
    • ‫LOG_ID_NAME בשם היומן
    //BQSH PROC
//*******************************************************************
//*
//* Copyright 2022 Google LLC All Rights Reserved
//*
//* Licensed under the Apache License, Version 2.0 (the "License");
//* you may not use this file except in compliance with the License.
//* You may obtain a copy of the License at
//*
//*     http://www.apache.org/licenses/LICENSE-2.0
//*
//* Unless required by applicable law or agreed to in writing, software
//* distributed under the License is distributed on an "AS IS" BASIS,
//* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//* See the License for the specific language governing permissions and
//* limitations under the License.
//*
//*******************************************************************
//BQSH EXEC PGM=JVMLDM86,REGION=0M,
//  PARM='/+I com.google.cloud.bqsh.Bqsh'
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//CEEDUMP  DD SYSOUT=*
//ABNLIGNR DD DUMMY
//STDIN    DD DUMMY
//QUERY    DD DUMMY
//INFILE   DD DUMMY
//COPYBOOK DD DUMMY
//KEYFILE  DD DUMMY
//STDENV   DD *,SYMBOLS=EXECSYS

# Service Account Keyfile
# Edit the line below to specify a unix filesystem path where
# the service account keyfile is stored.
# The service account should be granted Storage, BigQuery and Logging permissions.
export GKEYFILE="GKEY_FILE_PATH"

# Path to directory containing google jar file
# Edit this to set actual path selected for your site
# it's recommended to have a path with a version identifier
# and create a symlink to the directory of the latest version
GOOGLE_DIR="JAR_FILE_PATH"
GOOGLE_CLASSPATH="$GOOGLE_DIR/*"

# Do not modify the 3 lines below
# Collect system symbols from JES
export JOBNAME=&JOBNAME
export JOBDATE=&YYMMDD
export JOBTIME=&HHMMSS

# IBM JZOS JDK Location
JH="/usr/lpp/java/J8.0_64"
export JAVA_HOME="$JH"
export PATH="/bin:$JH/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

# Cloud logging
export LOG_PROJECT="PROJECT_NAME"
export LOG_ID="LOG_ID_NAME"

# Binary Data Sets
# Uncomment the line below to set a default output bucket for scp.
# The DSN of the input file is used as the object name.
# this may greatly reduce effort across many job steps
#export GCSDSNURI="gs://[BUCKET]/[PREFIX]"

# Generational Data Sets
# Uncomment the line below to set a default output bucket for scp GDG datasets.
# The Cloud GDG feature emulates a GDG dataset in a versioned object.
# Cloud Storage objects take precedence over local DSN when this is set.
#export GCSGDGURI="gs://[BUCKET]/[PREFIX]"

# Uncomment the line below to set a default output bucket for the gszutil command.
#export GCSOUTURI="gs://[BUCKET]/[PREFIX]"

# Mainframe Connector gRPC service
# Uncomment and edit the lines below to set the Hostname or IP Address and
# port of the gRPC data set transcoding service.
# The gRPC service converts z/OS datasets to ORC format on VMs running in
# Google Cloud VPC. This is strongly recommended when processing high volumes
# of data.
#export SRVREMOTE=
#export SRVPORT=

# Native Libraries
JL="$JH/lib"
LP="/lib:/usr/lib:$JH/bin:$JL/s390x:$JL/s390x/j9vm:$JH/bin/classic"
export LIBPATH="$LP:/usr/lib/java_runtime64"

# Java Classpath
CP="$JL:$JL/ext:/usr/include/java_classes/*"
export CLASSPATH="$CP:$GOOGLE_CLASSPATH"

# JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
export IBM_JAVA_OPTIONS="$IJO"
export JZOS_MAIN_ARGS=""
/*
// PEND

  8. כדי להגדיר את Mainframe Connector לעבודה עם שרת proxy שחוצה את חיבור ה-TLS, צריך להגדיר את מאפייני המערכת הבאים של Java בהליך BQSH JCL.

    • javax.net.ssl.trustStore
    • javax.net.ssl.trustStorePassword
    • https.proxyHost
    • https.proxyUser
    • https.proxyPassword

    הנה הפרוצדורה של BQSH JCL לפני הוספת מאפייני המערכת של Java עבור IBM_JAVA_OPTIONS.

    # JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
export IBM_JAVA_OPTIONS="$IJO"
 ```

The BQSH JCL procedure after adding the Java system properties for
<code>IBM_JAVA_OPTIONS</code> is as follows.

```none
# JVM options
IJO="-Xms512m -Xmx512m -Xcompressedrefs -Djava.net.preferIPv4Stack=true"
IJO="$IJO -Djavax.net.ssl.trustStore=/path/to/cacerts"
IJO="$IJO -Djavax.net.ssl.trustStorePassword=notasecret"
IJO="$IJO -Dhttp.proxyHost=proxy.example.com"
IJO="$IJO -Dhttp.proxyUser=username"
IJO="$IJO -Dhttp.proxyPassword=password"
export IBM_JAVA_OPTIONS="$IJO"
 ```

  9. אם אתם משתמשים בסיסמה changeit של מאגר האישורים המהימנים המוגדר כברירת מחדל, אינכם צריכים להגדיר את מאפיין המערכת trustStorePassword. יכולות ה-proxy מסופקות על ידי Apache HttpComponents HttpClient.

    חובה להשתמש בפורמט של מאגר אישורים שנתמך על ידי Mainframe Connector. אפשר לאחסן את מאגר האישורים המהימן בפורמטים הבאים:

    • ‫PKCS12 ‏ (.p12): יכול להכיל אישורים רבים ונדרשת סיסמה
    • ‫JKS ‏(‎.jks): יכול להכיל הרבה אישורים ונדרשת סיסמה
    • ‫PEM ‏ (.pem): יכול להכיל הרבה אישורים בקידוד base64
    • בינארי (‎.der): מכיל אישור אחד לכל קובץ

    אם מאפיין המערכת trustStore הוא הנתיב לספרייה, המערכת סורקת את הספרייה ומוסיפה כאישורים מהימנים את כל האישורים בפורמט ‎.pem ו-‎.der שנמצאים בספרייה. צריך לטעון ידנית אישורי PKCS12 או JKS.

אם צריך לבצע שינויים בהליך BQSH JCL בכל שלב, אפשר להכין גרסה חדשה יותר בסביבה התחתונה בספריית ההליכים (PROCLIB). הספרייה הזו מתווספת לפני ספריית המערכת, SYSP.PROCLIB, כך שאפשר לבדוק את השינויים בסביבה התחתונה לפני שמעדכנים את הפרוצדורה ב-SYSP.PROCLIB. כך אפשר להימנע מעדכון של פרוצדורות JCL כדי שיצביעו על פרוצדורה חדשה ומעודכנת במהלך הבדיקה.

דוגמה לפרוצדורת BQSH JCL

הנה דוגמה לפרוצדורת BQSH JCL. בפרוצדורה הזו, הסמל ENV משמש להפניה להצהרות של סביבת Java רגילה, והוא ספציפי לסביבת Google Cloud . כך לא תצטרכו לבצע כמה פעולות BQSH לכל סביבה. אם רוצים לבצע שינויים בסביבה מסוימת, צריך לעדכן רק את החבר הספציפי הזה בסביבהGoogle Cloud בספריית PARMLIB של המערכת. לדוגמה, אפשר ליצור קובץ JAR חדש, להשתמש בגרסה אחרת של IBM Java או לשנות את קובץ מפתח ה-JSON באמצעות הצהרות סביבה.

#BQSH PROC ENV=DEV
//
//******************************************************************
//*
//* Copyright 2022 Google LLC All Rights Reserved
//*
//* Licensed under the Apache License, Version 2.0 (the "License");
//* you may not use this file except in compliance with the License.
//* You may obtain a copy of the License at
//*      http://www.apache.org/licenses/LICENSE-2.0
//* Unless required by applicable law or agreed to in writing , software
//* distributed under the License is distributed on as "AS IS" BASIS,
//* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express of impl.
//* See the license for the specific language governing permissions and
//* limitations under the License.
//*
//******************************************************************
//BQSH EXEC PGM=JVMLDM86,REGION=0M,
//  PARM='/+I com.google.cloud.bqsh.Bqsh'
//SYSPRINT DD SYSOUT = *
//SYSOUT   DD SYSOUT = *
//STDOUT   DD SYSOUT = *
//STDERR   DD SYSOUT = *
//CEEDUMP  DD SYSOUT = *
//ABNLIGNR DD DUMMY
//STDIN    DD DUMMY
//QUERY    DD DUMMY
//INFILE   DD DUMMY
//COPYBOOK DD DUMMY
//KEYFILE  DD DUMMY
//STDENV   DD DISP=SHR,DSN=SYSP.PARMLIB(EDW&ENV)
//         DD *,SYMBOLS=EXECSYS
# Do not modify the 3 lines below
# Collect system symbols from JES
export JOBNAME=&JOBNAME
export JOBDATE=&YYMMDD
export JOBTIME=&HHMMSS

בדוגמה הבאה מוצג חבר DEV PARMLIB שמראה איך מתבצעת הפניה לקובץ מפתח JSON ול-JAR של תוכנת Mainframe Connector.

# Service Account Keyfile
# Edit the line below to specify a unix filesystem path where
# the service account keyfile is stored.
# The service account should be granted Storage, BigQuery and Logging pe
GKPATH= "/opt/google/keyfile"
GKFILE= "prj-ent-edw-dev-landing-2451-f89d99af31e5.json"
export GKEYFILE= "$GKPATH/$GKFILE"

# Path  to directory containing google jar file
# Edit this is set actual path selected for your site
# its recommended to have a path with a version identifier
# and create a symlink to the directory of the latert version
GOOGLE_DIR= "/opt/google/mainframe-connector/5.9.0"
GOOGLE_CLASSPATH= "$GOOGLE_DIR/*"

#IBM JZOS JDK Location
JH= "/usr/lpp/java/J8.0_64"
export JAVA_HOME= "$JH"
export PATH= "/bin:$JH/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

המאמרים הבאים