Instalar o Mainframe Connector no mainframe

O Mainframe Connector é iniciado como um processo de máquina virtual Java (JVM) no contexto de um job em lote do MVS. O Mainframe Connector geralmente é implantado usando um arquivo JAR que contém algumas dependências necessárias além das bibliotecas da IBM incluídas na JVM. As seções a seguir descrevem o processo de instalação do Mainframe Connector em detalhes.

Antes de começar

  • Conclua a configuração inicial do Mainframe Connector. A configuração inicial inclui conceder os papéis necessários à sua conta de serviço, configurar a segurança dos seus recursos e configurar a conectividade 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).

Instalar o Mainframe Connector

Para instalar o Mainframe Connector, siga estas etapas:

  1. Faça o download do arquivo JAR do Mainframe Connector pré-criado em um diretório em que sua conta de usuário tenha permissões de gravação.

    Importante

    Esteja ciente de que o Mainframe Connector usa o Google Analytics para coletar dados de uso. Isso nos ajuda a melhorar o software e oferecer uma experiência melhor para o usuário. Por padrão, o Google Analytics está ativado. No entanto, é possível desativar a coleta configurando uma variável de ambiente ao executar o Mainframe Connector.

    O uso do Google Analytics está sujeito aos Termos de Serviço e à Política de Privacidade do Google Analytics. Ao fazer o download do Mainframe Connector, você confirma que leu, entendeu e aceitou os Termos e Condições.

    Fazer o download Cancelar

  2. Copie o arquivo mainframe-connector-shadow-VERSION-all.jar para o caminho especificado na seção Classpath do Java do linguagem de controle de jobs (JCL) do BQSH, conforme mostrado na etapa 8. VERSION é a versão do Mainframe Connector.

  3. Para acessar os serviços do Google Cloud no mainframe, crie e faça o download de uma chave de conta de serviço como um arquivo de chave JSON. Para mais informações sobre como criar um arquivo de chave JSON, consulte Criar uma chave de conta de serviço.

  4. Copie o arquivo de chave JSON para o sistema de arquivos Unix usando o protocolo de transferência de arquivos (FTP) no modo de transferência binária. Armazene o arquivo de chave JSON sem modificações no sistema de arquivos, com a codificação UTF-8 original.

    Não há um caminho padrão para armazenar o arquivo de chave JSON no sistema de arquivos IBM z/OS Unix. Escolha um caminho que possa ser lido apenas por usuários com permissões para acessar a conta de serviço. O arquivo de chave JSON não poderá ser lido pelos serviços do sistema UNIX (USS) se tiver sido transferido corretamente.

  5. Use o FTP no modo binário para fazer upload do arquivo JAR baixado na etapa 1 para o seguinte local no mainframe.

     /opt/google/mainframe-connector/VERSION/

    Substitua Version pela versão do arquivo JAR.

    Este é o caminho recomendado para implantar o arquivo JAR. Você também pode usar qualquer caminho escolhido por um administrador do site.

  6. Execute o comando a seguir para validar se o arquivo JAR foi transferido corretamente. A opção -t lista o conteúdo do arquivo JAR.

     jar -tvf JAR_FILE_NAME

    Substitua JAR_FILE_NAME pelo nome do arquivo JAR.

  7. Faça uma cópia do seguinte procedimento JCL do BQSH.

    /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

    Substitua:

    • GKEY_FILE_PATH: o caminho para o arquivo de chave JSON descrito na etapa 3.
    • JAR_FILE_PATH: o caminho para o diretório que contém o arquivo JAR.
    • PROJECT_NAME: o projeto para o qual o registro está sendo criado no Cloud Logging.
    • LOG_ID_NAME: o nome do registro.
    • Para desativar a geração de registros de depuração, comente a linha BQSH_ROOT_LOGGER=DEBUG.
    • Para configurar o Mainframe Connector para gravar informações de registro no Cloud Logging, defina as variáveis de ambiente LOG_PROJECT e LOG_ID.
    • Para desativar o Google Analytics, defina a variável de ambiente DISABLE_ANALYTICS como True.

    Para conferir a lista completa de variáveis de ambiente compatíveis com o Mainframe Connector, consulte Variáveis de ambiente.

  8. Para configurar o Mainframe Connector para trabalhar com um proxy de interceptação de TLS, defina as seguintes propriedades do sistema Java no procedimento JCL 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 você estiver usando a senha padrão do repositório de confiança changeit, não será necessário definir a propriedade do sistema trustStorePassword. Os recursos de proxy são fornecidos pelo Apache HttpComponents HttpClient.

    Você precisa usar um formato de repositório de confiança de certificado compatível com o Mainframe Connector. O repositório de confiança de certificados pode ser armazenado nos seguintes formatos:

    • PKCS12 (.p12): pode conter muitos certificados e exige uma senha.
    • JKS (.jks): pode conter muitos certificados e exige uma senha.
    • PEM (.pem): pode conter vários certificados codificados como base64
    • Binário (.der): contém um certificado por arquivo.

    Se a propriedade de sistema trustStore for o caminho para um diretório, ele será verificado, e todos os certificados com os formatos .pem e .der encontrados no diretório serão adicionados como certificados confiáveis. É necessário carregar manualmente os certificados PKCS12 ou JKS.

Se você precisar fazer mudanças no procedimento BQSH JCL a qualquer momento, poderá preparar uma versão mais recente na biblioteca de procedimentos (PROCLIB) do ambiente inferior. Essa biblioteca é adicionada antes da biblioteca do sistema, SYSP.PROCLIB. Assim, as mudanças podem ser verificadas no ambiente inferior antes de atualizar o procedimento em SYSP.PROCLIB. Assim, você evita atualizar os procedimentos JCL para apontar para um novo procedimento atualizado durante o teste.

Exemplo de procedimento JCL do BQSH

Confira a seguir um exemplo de procedimento JCL do BQSH. Neste procedimento, o símbolo ENV é usado para apontar para as instruções do ambiente padrão do Java e é específico do ambiente Google Cloud . Assim, não é necessário ter vários procedimentos BQSH para cada ambiente. Se você quiser fazer mudanças em um ambiente específico, basta atualizar esse membro no ambienteGoogle Cloud na biblioteca PARMLIB do sistema. Por exemplo, crie um novo arquivo JAR, use uma versão diferente do IBM Java ou mude o arquivo de chave JSON usando instruçõ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

Confira um exemplo do membro DEV PARMLIB que mostra como o arquivo de chave JSON e o arquivo JAR do software Mainframe Connector 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

A seguir