Instale o Mainframe Connector no mainframe

O conetor de mainframe é iniciado como um processo de máquina virtual Java (JVM) no contexto de um trabalho em lote MVS. Normalmente, o Mainframe Connector é implementado através de um ficheiro JAR que contém algumas dependências necessárias além das bibliotecas IBM incluídas na JVM. As secções seguintes descrevem o processo de instalação do conetor de mainframe em detalhe.

Antes de começar

  • Conclua a configuração inicial do conetor de mainframe. A configuração inicial inclui a concessão das funções necessárias à sua conta de serviço, a configuração da segurança dos seus recursos e a configuração da conetividade de rede entre o mainframe e o Google Cloud.
  • Configure o Java 8 ou o Java 17.
  • Instale o JZOS Batch Launcher and Toolkit (Java 8 ou Java 17).

Instale o conetor de mainframe

Para instalar o Mainframe Connector, siga estes passos:

  1. Transfira o ficheiro JAR do conector do mainframe pré-criado para um diretório no qual a sua conta de utilizador tenha autorizações de escrita.

    Importante

    Tenha em atenção que o Mainframe Connector usa o Google Analytics para recolher dados de utilização. Isto ajuda-nos a melhorar o software e oferecer uma melhor experiência do utilizador. Por predefinição, o Google Analytics está ativado. No entanto, pode desativar esta opção configurando uma variável de ambiente quando executar o Mainframe Connector.

    A utilização do Google Analytics está sujeita aos Termos de Utilização e à Política de Privacidade do Google Analytics. Ao transferir o Mainframe Connector, confirma que leu, compreendeu e aceitou os termos de utilização.

    Transferir Cancelar

  2. Copie o ficheiro mainframe-connector-shadow-VERSION-all.jar para o caminho especificado na secção Java Classpath do procedimento de linguagem de controlo de tarefas (JCL) do BQSH apresentado no passo 8. VERSION é a versão do Mainframe Connector.

  3. Para aceder aos Google Cloud serviços a partir do seu mainframe, tem de criar e transferir uma chave de conta de serviço como um ficheiro de chave JSON. Para mais informações sobre como criar um ficheiro de chave JSON, consulte o artigo Crie uma chave de conta de serviço.

  4. Copie o ficheiro de chave JSON para o sistema de ficheiros Unix através do protocolo de transferência de ficheiros (FTP) no modo de transferência binária. Certifique-se de que armazena o ficheiro de chave JSON não modificado no sistema de ficheiros com a codificação UTF-8 original.

    Não existe um caminho predefinido para armazenar o ficheiro de chave JSON no sistema de ficheiros Unix do IBM z/OS. Tem de escolher um caminho que só seja legível por utilizadores com autorizações para aceder à conta de serviço. O ficheiro de chave JSON não vai ser legível a partir dos serviços do sistema UNIX (USS) se tiver sido transferido corretamente.

  5. Use o FTP no modo binário para carregar o ficheiro JAR que transferiu no passo 1 para a seguinte localização no seu computador central.

     /opt/google/mainframe-connector/VERSION/

    Substitua Version pela versão do ficheiro JAR.

    Tenha em atenção que este é o caminho recomendado para implementar o ficheiro JAR. Também pode usar qualquer caminho escolhido por um administrador do site.

  6. Execute o seguinte comando para validar se o ficheiro JAR foi transferido corretamente. Tenha em atenção que a opção -t apresenta o conteúdo do ficheiro JAR.

     jar -tvf JAR_FILE_NAME

    Substitua JAR_FILE_NAME pelo nome do ficheiro JAR.

  7. Faça uma cópia do procedimento JCL BQSH seguinte e substitua as seguintes variáveis.

    No procedimento JCL BQSH, BQSH_ROOT_LOGGER=DEBUG indica que o registo de depuração está ativado. Para desativar o registo de depuração, comente a linha ou defina a variável para qualquer valor que não seja DEBUG.

    Para configurar o Mainframe Connector para escrever informações de registo no Cloud Logging, defina as variáveis de ambiente LOG_PROJECT e LOG_ID, conforme mostrado no exemplo seguinte.

    Para ver a lista completa de variáveis de ambiente suportadas pelo Mainframe Connector, consulte o artigo Variáveis de ambiente.

    • GKEY_FILE_PATH com o caminho para o ficheiro de chave JSON descrito no passo 3.
    • JAR_FILE_PATH com o caminho para o diretório que contém o ficheiro JAR.
    • PROJECT_NAME com o projeto para o qual o registo está a ser criado no Cloud Logging
    • LOG_ID_NAME com o nome do registo
    //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. Para configurar o Mainframe Connector para funcionar com um proxy de interceção de TLS, defina as seguintes propriedades do sistema Java no procedimento JCL do BQSH.

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

    O procedimento JCL do BQSH antes de adicionar as propriedades do sistema Java para IBM_JAVA_OPTIONS é o seguinte.

    # 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. Se estiver a usar a palavra-passe da loja de confiança predefinida changeit, não tem de definir a propriedade do sistema trustStorePassword. As capacidades de proxy são fornecidas por Apache HttpComponents HttpClient.

    Tem de usar um formato de repositório fidedigno de certificados suportado pelo Mainframe Connector. O repositório de confiança de certificados pode ser armazenado nos seguintes formatos:

    • PKCS12 (.p12): pode conter muitos certificados e requer uma palavra-passe
    • JKS (.jks): pode conter muitos certificados e requer uma palavra-passe
    • PEM (.pem): pode conter muitos certificados codificados como base64
    • Binário (.der): contém um certificado por ficheiro

    Se a propriedade do sistema trustStore for o caminho para um diretório, o diretório é analisado e todos os certificados com o formato .pem e .der encontrados no diretório são adicionados como certificados fidedignos. Tem de carregar manualmente certificados PKCS12 ou JKS.

Se precisar de fazer alterações ao procedimento JCL do BQSH em qualquer altura, pode preparar uma versão mais recente na biblioteca de procedimentos (PROCLIB) do ambiente inferior. Esta biblioteca é adicionada antes da biblioteca do sistema, SYSP.PROCLIB, para que as alterações possam ser validadas em relação ao ambiente inferior antes de atualizar o procedimento em SYSP.PROCLIB. Desta forma, pode evitar a atualização de procedimentos JCL para apontar para um novo procedimento atualizado durante os testes.

Exemplo de procedimento JCL BQSH

Segue-se um exemplo de um procedimento JCL BQSH. Neste procedimento, o símbolo ENV é usado para apontar para as declarações do ambiente padrão Java e é específico do ambiente Google Cloud . Desta forma, não precisa de vários procedimentos de BQSH para cada ambiente. Se quiser fazer alterações para um ambiente específico, basta atualizar esse membro específico na bibliotecaGoogle Cloud environment in system PARMLIB. Por exemplo, crie um novo ficheiro JAR, use uma versão Java da IBM diferente ou altere o ficheiro de chave JSON usando declarações de ambiente.

#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

Segue-se um exemplo do membro DEV PARMLIB que mostra como o ficheiro de chave JSON e o ficheiro JAR do software do conetor de mainframe são referenciados.

# 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

O que se segue?