Referencia de la API de Mainframe Connector

En la siguiente tabla, se enumeran los comandos de BigQuery, Cloud Storage y otros comandos de Google Cloud que puedes usar con el conector de Mainframe.

Producto Comando Descripción Admite la transcodificación remota
Comandos de BigQuery Usa este comando para crear un archivo binario. El comando acepta un COPYBOOK DD como entrada.

El comando bq export admite algunas capacidades de ajuste de rendimiento. Para obtener más información, consulta Mejoras de rendimiento del comando bq export.

Puedes usar conjuntos de caracteres personalizados con el comando bq export. Para obtener más información, consulta Usa conjuntos de caracteres personalizados.

Nota: El comando bq export falla en las solicitudes para exportar tablas grandes de Bigtable. Para evitar errores, agrega la marca -allowLargeResults al comando bq export cuando quieras exportar tablas grandes.		 Sí
Usa este comando para cargar datos en una tabla. Para obtener más información, consulta bq load. No
Usa este comando para crear recursos de BigQuery, como tablas integradas o externas, que necesitan particiones y clústeres para configurarse. Para obtener más información, consulta bq mk.

También puedes usar el comando bq mk para generar una tabla de BigQuery directamente a partir del análisis de libros de copia de COBOL. Para obtener más información, consulta Cómo crear una tabla de BigQuery a partir de un libro de copia. 		No
Usa este comando para crear un trabajo de consulta que ejecute la consulta en SQL especificada. El comando lee la consulta en SQL desde la marca --sql o desde QUERY DD. Si se proporcionan ambos, la consulta en la marca --sql tiene prioridad.

Usa la marca --follow=true para generar un informe que muestre los resultados de una consulta de selección. Para escribir este informe en un archivo en el sistema de procesamiento principal, define una sentencia DD AUDITL que apunte al archivo que debe contener el informe de registros de auditoría. No uses la marca --follow si deseas un comportamiento de registro normal.

Algunos resultados de la consulta pueden mostrar una gran cantidad de filas, a veces en millones. Para que el resultado siga siendo legible por humanos, se limita la cantidad de líneas que se muestran. Para controlar la cantidad de filas que se muestran, usa la marca --report_row_limit. Por ejemplo, usa --report_row_limit 10 para limitar los resultados a 10 líneas. De forma predeterminada, la cantidad de líneas que se muestran se limita a 30.

Para usar la parametrización de bq query, consulta parametrización de consultas de bq.

Para obtener más información, consulta bq query. 		Sí
Usa este comando para borrar de forma permanente un recurso de BigQuery. Como este comando borra un recurso de forma permanente, te recomendamos que lo uses con precaución. Para obtener más información, consulta bq rm. No
Comandos de Cloud Storage Usa este comando para copiar datos binarios o de texto a Cloud Storage. Puedes usar el modo de copia binaria simple para copiar un conjunto de datos de IBM z/OS a Cloud Storage sin modificaciones como parte de una canalización de datos. De manera opcional, puedes convertir la codificación de caracteres del código de intercambio decimal codificado en binario extendido (EBCDIC) a ASCII UTF-8 y agregar saltos de línea.

También puedes usar este comando para copiar el código fuente de la aplicación definido en el lenguaje de control de trabajos (JCL). 		No
Utilidad gsutil Usa este comando para transcodificar un conjunto de datos y escribirlo en Cloud Storage en el formato de archivo Optimized Row Columnar (ORC). El comando lee los datos del DD INFILE y el diseño de registro del archivo COPYBOOK. Si deseas que el comando lea los datos de un archivo de nombre de fuente de datos (DSN), usa las siguientes marcas:
  • --inDsn: El DSN del conjunto de datos de entrada. Si se proporciona, esta marca anula el DD INFILE.
  • --cobDsn: El DSN del libro de copia Si se proporciona, esta marca anula COPYBOOK DD.


Luego, el comando abre una cantidad configurable de conexiones en paralelo a la API de Cloud Storage y transcodifica el conjunto de datos de COBOL al formato de archivo ORC comprimido en columnas y GZIP. Puedes esperar un índice de compresión de alrededor del 35%.

De forma opcional, puedes usar este comando para interactuar con el servicio de gRPC del conector de Mainframe que se ejecuta en una VM en el mainframe. Para ello, configura las variables de entorno SRVHOST y SRVPORT, o proporciona el nombre de host y el número de puerto con las opciones de línea de comandos. Cuando se usa el servicio de gRPC, el conector de Mainframe primero copia el conjunto de datos de entrada en Cloud Storage y, luego, se realiza una llamada de procedimiento remoto (RPC) para indicarle al servicio de gRPC que transcodifique el archivo.

También puedes realizar las siguientes tareas con el comando gsutil cp: 		Sí
Usa este comando para borrar buckets u objetos dentro de un bucket. Para obtener más información, consulta rm: Quita objetos. No
Utilidad gszutil La utilidad gszutil se ejecuta con el SDK de Java de IBM JZOS y proporciona un emulador de shell que acepta invocaciones de línea de comandos de gsutil y BigQuery con JCL.

La utilidad gszutil extiende la funcionalidad de la utilidad gsutil, ya que acepta un esquema en forma de COPYBOOK DD y lo usa para transcodificar conjuntos de datos de COBOL directamente a ORC antes de subirlos a Cloud Storage. La utilidad gszutil también te permite ejecutar query y load de BigQuery con JCL.

La utilidad gszutil funciona con el servidor gRPC, que te ayuda a reducir el consumo de millones de instrucciones por segundo (MIPS). Te recomendamos que uses la utilidad gszutil en tu entorno de producción para convertir archivos binarios en Cloud Storage al formato ORC. 		No
Otros comandos Usa este comando para enviar un mensaje a un tema de Pub/Sub. Puedes proporcionar el mensaje con la línea de comandos o con un conjunto de datos. No
Usa este comando para activar la ejecución de una plantilla de Dataflow flex. El comando ejecuta un trabajo desde la ruta de acceso de la plantilla flexible especificada. Para obtener más información, consulta gcloud dataflow flex-template run. No
Usa este comando para realizar una solicitud HTTP a un servicio web o a APIs de REST. No
Usa este comando para imprimir los datos del sistema necesarios en la salida estándar (stdout). Esto permite que el equipo de asistencia al cliente de Mainframe Connector recopile la información necesaria para diagnosticar un problema sin necesidad de una interacción extensa con el cliente.
Según la marca que uses, el comando systemreport imprime los siguientes datos del sistema:
  • --supported_ciphers: Cifrado compatible
  • --available_security_providers: Proveedores de seguridad disponibles
 No

Usa conjuntos de caracteres personalizados

Mainframe Connector admite diferentes conjuntos de caracteres que decodifican bytes en cadenas de BigQuery y viceversa. Mainframe Connector te permite configurar tu propio conjunto de caracteres personalizado. Para configurar un grupo de caracteres personalizado, compila un archivo de asignación de caracteres Unicode (UCM). El conector de Mainframe admite el siguiente subconjunto del formato UCM:

<code_set_name>               "<name>"
<uconv_class>                 "SBCS"
<subchar>                     \x1A #Example

CHARMAP
#_______ _________
<U0000> \x00 |0       #For the third column, only 0 is supported.
<U0001> \x01 |0
#etc
END CHARMAP

Si deseas usar un grupo de caracteres personalizado, define un archivo de configuración en el formato UCM. Puedes usar este grupo de caracteres personalizado con los comandos gsutil cp o bq export si configuras la marca --encoding=charset.

Cuando crees un grupo de caracteres personalizado, asegúrate de lo siguiente:

  • Cuando definas un archivo UCM, ten en cuenta lo siguiente:
    • El conector de Mainframe solo admite conjuntos de caracteres personalizados con un grupo de caracteres de un solo byte (SBCS).
    • Mainframe Connector solo admite el indicador de precisión |0 de la UCM.
    • Asegúrate de que los archivos UCM se encuentren en los servicios del sistema Unix (USS) de z/OS y no en un conjunto de datos particionado de almacenamiento virtual múltiple (PDS de MVS).
    • Asegúrate de que los archivos UCM se guarden en formato American Standard Code for Information Interchange (ASCII) y no en formato Extended Binary Coded Decimal Interchange Code (EBCDIC).
  • Proporciona una asignación explícita de cada valor de byte único posible a un carácter Unicode. Si no sabes a qué carácter Unicode quieres asignar un byte, te recomendamos que lo asignes a U+FFFD. Puedes asignar diferentes secuencias de bytes al mismo carácter Unicode. Sin embargo, en estos casos, la asignación no es bidireccional, es decir, cuando cargas datos en BigQuery y, luego, los exportas a un archivo binario, el resultado podría diferir de la entrada original.
  • Asegúrate de que las secuencias de bytes de la segunda columna sean únicas. Si varias secuencias de bytes se asignan al mismo carácter Unicode, este se decodifica en una secuencia de bytes de la última asignación definida en el archivo UCM.
  • Para asegurarte de que el conector de Mainframe pueda encontrar el archivo UCM, configura la variable de entorno BQSH_FEATURE_CUSTOM_CHARSET en la ruta del archivo UCM. Si deseas usar varios conjuntos de caracteres, puedes proporcionar las rutas de acceso a varios conjuntos de caracteres separados por el delimitador punto y coma. Por ejemplo, BQSH_FEATURE_CUSTOM_CHARSET=path1;path2. path puede apuntar a un archivo local o a un archivo almacenado en Cloud Storage. Si ejecutas los comandos gsutil cp o bq export con la marca --remote para realizar la transcodificación remota, Mainframe Connector usa el valor local establecido para la variable de entorno BQSH_FEATURE_CUSTOM_CHARSET. Lo mismo ocurre cuando ejecutas Mainframe Connector en modo independiente. Si la marca --encoding hace referencia a un grupo de caracteres personalizado que no corresponde al valor que estableciste para BQSH_FEATURE_CUSTOM_CHARSET (o si no estableciste BQSH_FEATURE_CUSTOM_CHARSET), el comando se cierra con un mensaje de error.

Configuración de optimización del rendimiento para el comando bq export

El conector de Mainframe admite la siguiente configuración de optimización del rendimiento para el comando bq export:

  • exporter_thread_count: (Opcional) Establece la cantidad de subprocesos de trabajo. El valor predeterminado es 4.
  • max_read_streams: (Opcional) Establece las transmisiones de lectura máximas. El valor predeterminado es el mismo que el del valor establecido para exporter_thread_count.
  • order_response: (Opcional) Si estableces esta marca como verdadera, el exportador retiene el orden de los resultados de la consulta. Esta marca afecta el rendimiento de la exportación. El valor predeterminado es falso.
  • max_read_queue: (Opcional) Establece la cantidad máxima de colas de registros de lectura. El valor predeterminado es el doble de la cantidad de subprocesos.
  • transcoding_buffer: Establece el tamaño del búfer de transcodificación por subproceso en MB (opcional). El valor predeterminado es de 20 MB.

Ten en cuenta que también puedes intentar aumentar el tamaño de la ventana de transporte configurando la variable de entorno OVERRIDE_GRPC_WINDOW_MB para mejorar el rendimiento. El tamaño predeterminado de la ventana es de 4 MB.

Crea una tabla de BigQuery a partir de un libro de copia

Puedes usar el comando bq mk para generar una tabla de BigQuery directamente a partir del análisis de libros de copia de COBOL. El analizador de libros de copia nativos extrae valores predeterminados de la cláusula VALUE dentro de un libro de copia y los asigna a las columnas correspondientes en una tabla de BigQuery recién creada.

Para ayudarte a probar esta función, el comando bq mk también proporciona un modo de prueba sin conexión. Este modo te permite obtener una vista previa del comando CREATE TABLE SQL generado sin crear la tabla en BigQuery.

El comando bq mk proporciona las siguientes opciones de configuración para admitir esta función:

  • --schema_from_copybook: Especifica el libro de copia que se usará para crear la tabla.
  • --dry_run: (Opcional) Cuando está habilitado, el comando solo imprime el comando CREATE TABLE SQL generado sin ejecutarlo. Esta marca se establece como "false" de forma predeterminada.
  • --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": Especifica el ID del proyecto, el conjunto de datos y el nombre de la tabla de BigQuery para la tabla de destino.
  • --encoding: Especifica la codificación que se usa para leer el archivo de libro de copia. El valor predeterminado es CP037.

Se admiten las siguientes cláusulas VALUE:

VAR1   PIC 9(5) VALUE 55.
*-- Set VAR1 to 55
VAR1   PIC X(5) VALUE aaaa. Set VAR1 to aaaa
VAR1   PIC 9(3) COMP VALUE 3. Set VAR1 to 3 (binary)
VAR1   PIC [9(5), X(5)] VALUE <literal>. Set VAR1 to <literal>
VAR1   PIC [9(5), X(5)] VALUE ZERO. Set VAR1 to 0 or "0"
VAR1   PIC [9(5), X(5)] VALUE ZEROS. Set VAR1 to 0 or "00000"
VAR1   PIC [9(5), X(5)] VALUE ZEROES. Set VAR1 to 0 or "00000"
VAR1   PIC X(5) VALUE SPACE. Set VAR1 to  " "
VAR1   PIC X(5) VALUE SPACES. Set VAR1 to  "     "

Las cláusulas HIGH-VALUE y LOW-VALUE solo son compatibles con las variables alfanuméricas.

VAR1   PIC X(5) VALUE HIGH-VALUE. Set VAR1 to `X"FF "
VAR1   PIC X(5) VALUE HIGH-VALUES. Set VAR1 to 0 or `X"FFFFFFFFFF"
VAR1   PIC X(5) VALUE LOW-VALUE. Set VAR1 to `X"00" (NULL)
VAR1   PIC X(5) VALUE LOW-VALUES. Set VAR1 to `X"0000000000" (NULL)
VAR1   PIC X(5) VALUE QUOTE. Set VAR1 to `"`
VAR1   PIC X(5) VALUE `QUOTES`. Set VAR1 to 0 or `""""`
VAR1   PIC [9(5), X(5)] VALUE NULL. Not defined and won't be supported
VAR1   PIC [9(5), X(5)] VALUE ALL <literal>. Set all fields with the value ALL to <literal>

Parametrización de bq query

Mainframe Connector te permite usar consultas con parámetros con bq query.

El siguiente es un ejemplo de cómo puedes usar una consulta bq query con parámetros:

Archivo de consulta

SELECT * FROM `bigquery-public-data.samples.wikipedia` WHERE title = @xtitle

El siguiente es un ejemplo con varios parámetros.

Archivo de consulta

SELECT * FROM bigquery-public-data.samples.wikipedia WHERE title = @mytitle AND num_characters > @min_chars;

Ejemplo de ejecución

bq query \
--project_id=mainframe-connector-dev \
--location="US" \
--parameters=mytitle::Hippocrates,min_chars:INT64:42600

Realiza una ejecución de prueba del comando gsutil cp

El comando gsutil cp decodifica un archivo de método de acceso secuencial en cola (QSAM) con un libro de copia de COBOL y genera un archivo ORC en Cloud Storage. Puedes realizar una prueba de validación del comando gsutil cp con la marca dry_run y probar los siguientes pasos:

  • Analiza un libro de copia o un archivo de datos de COBOL y verifica si es compatible con el conector de Mainframe.
  • Decodifica un archivo QSAM sin escribirlo en Cloud Storage.

Usa el siguiente comando para realizar una prueba de validación:

gsutil cp \
--dry_run \
gs://result-dir

Si todos los pasos se ejecutan correctamente, el comando se cierra con el código de retorno 0. Si se produce algún problema, aparecerá un mensaje de error.

Cuando usas la marca dry_run, se registran todas las estadísticas, como el total de bytes leídos, la cantidad de registros escritos y el total de errores.

Si usas la marca dry_run y la fuente de datos no existe, el comando no muestra un error. En su lugar, solo verifica el analizador de libros de copia y, luego, completa la ejecución.

Cómo copiar un archivo de Cloud Storage a tu mainframe

Puedes usar el comando gsutil cp para copiar un archivo de Cloud Storage a un conjunto de datos de Mainframe. Ten en cuenta que no puedes copiar conjuntos de datos particionados (PDS).

Para copiar un archivo de Cloud Storage a un conjunto de datos de Mainframe, especifica el DSN y los requisitos de espacio del archivo que deseas descargar en el Mainframe en JCL, como se muestra en el siguiente ejemplo:

//OUTFILE  DD DSN=MAINFRAME.DSN.FILE,DISP=(,CATLG),
//            RECFM=FB,DSORG=PS,
//            SPACE=(10,(2,1),RLSE),
//            AVGREC=M,
//            UNIT=SYSDA
//SYSPRINT DD SYSOUT=*
//SYSDUMP  DD SYSOUT=*
//STDIN DD *

Especifica el comando gsutil cp en el siguiente formato. Si el archivo ya existe en tu mainframe, asegúrate de agregar la marca --replace al comando.

gsutil cp GCS_URI DSN --recfm=RECFM --lrecl=LRECL --blksize=BLKSIZE --noseek

Reemplaza lo siguiente:

  • GCS_URI: Es el identificador de recursos uniforme (URI) de Cloud Storage del archivo de Cloud Storage. Por ejemplo, gs://bucket/sample.mainframe.dsn
  • DSN: Es la ubicación de destino del DSN en el mainframe.
  • RECFM: Es el formato de registro (RECFM) del archivo de Mainframe. Los valores válidos son F, FB y U. Ten en cuenta que estos valores no distinguen mayúsculas de minúsculas.
  • LRECL: (Opcional) Es la longitud del registro (LRECL) del archivo. El valor debe ser un número entero mayor o igual que 0. Si no se especifica LRECL, se supone que el archivo está en el formato de registro de longitud no definida (U).
  • BLKSIZE: Es el tamaño del bloque del archivo (opcional). Si se establece en 0, el sistema determinará el tamaño de bloque óptimo. El valor debe ser un número entero mayor o igual que 0. Si no especificas un valor, el archivo se considerará como un archivo desbloqueado.
  • noseek: (Opcional) Incluye este parámetro si deseas mejorar el rendimiento de la descarga. Esta marca se establece en "false" de forma predeterminada, es decir, las operaciones de salto están habilitadas.

Ejemplo de ejecución

gsutil cp gs://sample-bucket/MAINFRAME.DSN.FILE MAINFRAME.DSN.FILE \
--lrecl=16 --blksize=0 --recfm=fb

Configuración de optimización del rendimiento para el comando gsutil cp

El conector de Mainframe admite la siguiente configuración de optimización del rendimiento para el comando gsutil cp.

  • Usa la marca --parallelism para establecer la cantidad de subprocesos. El valor predeterminado es 1 (subproceso único).
  • Usa el argumento --maxChunkSize para establecer el tamaño máximo de cada fragmento. Cada fragmento tendrá su propio archivo ORC. Aumenta este valor para reducir la cantidad de fragmentos creados a costa de requisitos de memoria más grandes durante el proceso de transcodificación. Para obtener más información, consulta Cómo analizar el argumento maxChunkSize. El valor predeterminado es 128 MiB.
  • Usa el argumento --preload_chunk_count para establecer la cantidad de datos que se deben precargar en la memoria mientras todos los trabajadores están ocupados. Este argumento puede mejorar el rendimiento a costa de la memoria. El valor predeterminado es 2.

Ejemplo de ejecución

gsutil cp \
  --replace \
  --parser_type=copybook \
  --parallelism=8 \
  --maxChunkSize=256MiB \
  gs://$BUCKET/test.orc

En este ejemplo, consideramos un archivo grande y, por lo tanto, usamos 8 subprocesos en los que se alcanza la tasa de línea. Si tienes suficiente memoria, te recomendamos que aumentes el tamaño del fragmento a 256 MiB o incluso a 512 MiB, ya que reduce la sobrecarga de creación y la finalización de objetos de Cloud Storage. En el caso de los archivos pequeños, usar menos subprocesos y fragmentos más pequeños podría producir mejores resultados.

Analiza el argumento maxChunkSize

La marca maxChunkSize acepta valores en forma de un importe y una unidad de medida, por ejemplo, 5 MiB. Puedes usar espacios en blanco entre la cantidad y la magnitud.

Puedes proporcionar el valor en los siguientes formatos:

  • Formato Java: b/k/m/g/t, para byte, kibibyte, mebibyte, gibibyte y tebibyte, respectivamente
  • Formato internacional: KiB/MiB/GiB/TiB, para kibibyte, mebibyte, gibibyte y tebibyte, respectivamente
  • Formato métrico: b/kb/mb/gb/tb, para kilobytes, megabytes, gigabytes y terabytes, respectivamente

El análisis del tamaño de los datos no distingue mayúsculas de minúsculas. Ten en cuenta que no puedes especificar importes parciales. Por ejemplo, usa 716 KiB en lugar de 0.7 MiB.