התקנת 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 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
export GOOGLE_DIR="JAR_FILE_PATH"
export 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
export JAVA_HOME="/usr/lpp/java/J8.0_64"
export PATH="/bin:$JAVA_HOME/bin"

# Log Level
export BQSH_ROOT_LOGGER=DEBUG

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

# Google Analytics
# Uncomment the following line to disable Google Analytics
#export DISABLE_ANALYTICS=True

# Binary Data Sets
# Uncomment the following line 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
export JL="$JH/lib"
export 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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫GKEY_FILE_PATH: הנתיב לקובץ מפתח JSON שמתואר בשלב 3.
    • ‫JAR_FILE_PATH: הנתיב לספרייה שמכילה את קובץ ה-JAR.
    • ‫PROJECT_NAME: הפרויקט שעבורו נוצר היומן ב-Cloud Logging.
    • ‫LOG_ID_NAME: השם של היומן.
    • כדי להשבית את רישום ניפוי הבאגים, מוסיפים הערה לשורה BQSH_ROOT_LOGGER=DEBUG.
    • כדי להגדיר את Mainframe Connector כך שיכתוב פרטי רישום ביומן ל-Cloud Logging, מגדירים את משתני הסביבה LOG_PROJECT ו-LOG_ID.
    • כדי להשבית את Google Analytics, מגדירים את משתנה הסביבה DISABLE_ANALYTICS לערך True.

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

  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 ולתוכנת Mainframe Connector JAR.

# 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

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