Comandos de la API Mainframe Connector

En la siguiente tabla se enumeran los comandos de BigQuery, Cloud Storage y otros comandos deGoogle Cloud que puede usar con Mainframe Connector.

Nota: En los comandos que admiten la ejecución remota, puedes usar la opción remoteUrl en lugar de remoteHost y remotePort. La opción remoteUrl debe contener el esquema, el host y el puerto. Si el esquema es https y no se proporciona ningún almacén de confianza como opción trustCertCollectionFilePath o variable de entorno TRUST_CERT_COLLECTION_FILE_PATH, se usará el almacén de confianza predeterminado del sistema.

Producto	Comando	Descripción	Admite la transcodificación remota
Comandos de BigQuery	bq export	Usa este comando para crear un archivo binario. El comando acepta un COPYBOOK DD como entrada. Nota: Te recomendamos que uses los comandos qsam decode y qsam encode para llevar a cabo esta tarea. Para obtener información sobre las ventajas de usar los comandos qsam, consulta Ventajas de los comandos qsam. El comando bq export admite algunas funciones de ajuste del 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 Usar conjuntos de caracteres personalizados. Nota: El comando bq export no puede exportar tablas de Bigtable de gran tamaño. Para evitar errores, añade la marca -allowLargeResults al comando bq export cuando quieras exportar tablas grandes.	Sí
	bq load	Usa este comando para cargar datos en una tabla.	No
	bq mk	Usa este comando para crear recursos de BigQuery, como tablas integradas o tablas externas, que necesiten particiones y clústeres. También puedes usar el comando bq mk para generar una tabla de BigQuery directamente a partir del análisis de libros de copias de COBOL. Para obtener más información, consulta el artículo sobre cómo crear una tabla de BigQuery a partir de un copybook.	No
	bq query	Usa este comando para crear un trabajo de consulta que ejecute la consulta SQL especificada. El comando lee la consulta de SQL de la marca --sql o de QUERY DD. Si se proporcionan ambos, la consulta de la marca --sql tiene prioridad. Usa la marca --follow=true para generar un informe que muestre los resultados de una consulta seleccionada. Para escribir este informe en un archivo del mainframe, define una instrucción DD AUDITL que apunte al archivo que debe contener el informe de registros de auditoría. No uses la marca --follow si quieres que el registro se comporte con normalidad. Algunos resultados de consultas pueden devolver un gran número de filas, a veces millones. Para que el resultado siga siendo legible, se limita el número de líneas que se muestran. Para controlar el número 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, el número de líneas que se muestra está limitado a 30. Para usar la parametrización de bq query, consulta Parametrización de consultas de bq.	Sí
	bq rm	Usa este comando para eliminar permanentemente un recurso de BigQuery. Como este comando elimina un recurso de forma permanente, te recomendamos que lo uses con precaución.	No
Comandos de Cloud Run	cloud run job execute	Usa este comando para activar un trabajo de Cloud Run desde tu mainframe.	No
	cloud run job logs	Usa este comando para ver los registros de una ejecución de un trabajo de Cloud Run específico.	No
	cloud run job cancel	Usa este comando para cancelar una tarea de Cloud Run.	No
Comandos de Cloud Storage	scp	Usa este comando para copiar texto o datos binarios en Cloud Storage. Puedes usar el modo de copia binaria simple para copiar un conjunto de datos de IBM z/OS a Cloud Storage sin modificarlo como parte de una canalización de datos. Opcionalmente, puedes convertir la codificación de caracteres de código de intercambio decimal codificado en binario extendido (EBCDIC) a ASCII UTF-8 y añadir saltos de línea. Nota: Te recomendamos que uses los comandos copy text para realizar esta tarea, ya que ofrecen mejores funciones. También puedes usar este comando para copiar el código fuente de la aplicación definido en lenguaje de control de trabajos (JCL).	No
Utilidad gsutil	gsutil cp	Usa este comando para transcodificar un conjunto de datos y escribirlo en Cloud Storage con el formato de archivo Optimized Row Columnar (ORC). El comando lee los datos de INFILE DD y el diseño del registro del archivo COPYBOOK. Nota: Te recomendamos que uses los comandos qsam decode y qsam encode para llevar a cabo esta tarea. Para obtener información sobre las ventajas de usar los comandos qsam, consulta Ventajas de los comandos qsam. Si quiere que el comando lea los datos de un archivo de nombre de fuente de datos (DSN), use las siguientes marcas: --inDsn: el DSN del conjunto de datos de entrada. Si se proporciona, esta marca sustituye a INFILE DD. --cobDsn: el DSN del libro de copias. Si se proporciona, esta marca anula COPYBOOK DD. A continuación, el comando abre un número configurable de conexiones paralelas a la API Cloud Storage y transcodifica el conjunto de datos COBOL al formato de archivo ORC columnar y comprimido con GZIP. La relación de compresión será de aproximadamente el 35 %. También puedes usar este comando para interactuar con el servicio gRPC de Mainframe Connector que se ejecuta en una VM del mainframe. Para ello, define las variables de entorno SRVHOST y SRVPORT, o bien proporciona el nombre de host y el número de puerto mediante opciones de línea de comandos. Cuando se usa el servicio gRPC, Mainframe Connector copia primero el conjunto de datos de entrada en Cloud Storage y, a continuación, se hace una llamada a un procedimiento remoto (RPC) para indicar al servicio gRPC que transcodifique el archivo. También puedes realizar las siguientes tareas con el comando gsutil cp : Realizar una prueba de funcionamiento del comando gsutil cp Copiar un archivo de Cloud Storage en tu mainframe Ajustar el rendimiento del comando gsutil cp Usa conjuntos de caracteres personalizados con gsutil cp.	Sí
	gsutil rm	Usa este comando para eliminar segmentos u objetos de un segmento.	No
Utilidad gszutil	gszutil	La utilidad gszutil se ejecuta con el SDK de Java JZOS de IBM y proporciona un emulador de shell que acepta gsutil y invocaciones de línea de comandos de BigQuery mediante JCL. Nota: Te recomendamos que uses los comandos qsam decode y qsam encode para llevar a cabo esta tarea. Para obtener información sobre las ventajas de usar los comandos qsam, consulta Ventajas de los comandos qsam. La utilidad gszutil amplía la funcionalidad de la utilidad gsutil al aceptar un esquema en forma de COPYBOOK DD, usarlo 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 mediante 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 utilices la utilidad gszutil en tu entorno de producción para convertir archivos binarios de Cloud Storage al formato ORC.	No
Comandos de qsam	qsam decode	Usa este comando para transcodificar registros de archivos QSAM al formato que quieras con el argumento --output-format. El archivo QSAM original se divide en fragmentos según el valor que especifiques con el argumento --max-chunk-size. El resultado transcodificado se guarda en la ruta de destino como archivos ordenados lexicográficamente.	No
	qsam encode	Usa este comando para convertir datos de una fuente externa en un archivo QSAM. La entrada se define mediante el valor que especifiques con el argumento --input-format.	No
Comandos de Pub/Sub	pubsub topics publish	Usa este comando para publicar un mensaje en un tema de Pub/Sub.	No
Otros comandos	copy text	Usa este comando para copiar un archivo en la ubicación de almacenamiento que elijas, como Cloud Storage, y viceversa.	No
	curl	Usa este comando para enviar una solicitud HTTP a un servicio web o a APIs REST.	No
	gcloud dataflow flex-template run	Usa este comando para activar la ejecución de una plantilla flexible de Dataflow. El comando ejecuta una tarea desde la ruta de la plantilla flexible especificada. Para obtener más información, consulta gcloud dataflow flex-template run.	No
	systemreport	Usa este comando para imprimir los datos del sistema necesarios en la salida estándar (stdout). De esta forma, el equipo de asistencia de Mainframe Connector puede recopilar la información necesaria para diagnosticar un problema sin necesidad de que el cliente interactúe mucho. En función de la marca que uses, el comando systemreport imprimirá los siguientes datos del sistema: --supported_ciphers: cifrados admitidos --available_security_providers: proveedores de seguridad disponibles	No

Usar 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. Puedes configurar un conjunto de caracteres personalizado creando un archivo de asignación de caracteres Unicode (UCM). Mainframe Connector 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 quieres usar un conjunto de caracteres personalizado, define un archivo de configuración en formato UCM. Puedes usar este conjunto de caracteres personalizado con los comandos gsutil cp o bq export configurando la marca --encoding=charset.

Cuando crees un conjunto de caracteres personalizado, comprueba lo siguiente:

• Al definir un archivo UCM, ten en cuenta lo siguiente:
  • Mainframe Connector solo admite conjuntos de caracteres personalizados con un conjunto de caracteres de un solo byte (SBCS).
  • Mainframe Connector solo admite el indicador de precisión UCM |0.
  • Verifica que los archivos UCM se encuentren en los servicios del sistema Unix de z/OS (USS) y no en un conjunto de datos particionado de almacenamiento virtual múltiple (MVS PDS).
  • Verifique que los archivos UCM se hayan guardado en formato ASCII (American Standard Code for Information Interchange) y no en formato EBCDIC (Extended Binary Coded Decimal Interchange Code).
• Proporciona una asignación explícita para cada valor de un solo byte posible a un carácter Unicode. Si no sabes con certeza 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 carga datos en BigQuery y, posteriormente, los vuelve a exportar a un archivo binario, el resultado puede ser diferente de la entrada original.
• Verifica que las secuencias de bytes de la segunda columna sean únicas. Si varias secuencias de bytes se asignan al mismo carácter Unicode, este carácter Unicode se decodifica en una secuencia de bytes de la última asignación definida en el archivo UCM.
• Verifica que Mainframe Connector pueda encontrar el archivo UCM configurando la variable de entorno BQSH_FEATURE_CUSTOM_CHARSET en la ruta del archivo UCM. Si quieres usar varios conjuntos de caracteres, puedes proporcionar las rutas a varios conjuntos de caracteres separados por el delimitador de 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 una transcodificación remota, Mainframe Connector usará el valor local definido 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 conjunto de caracteres personalizado que no corresponde al valor que ha definido para BQSH_FEATURE_CUSTOM_CHARSET (o si no ha definido BQSH_FEATURE_CUSTOM_CHARSET), el comando se cierra con un mensaje de error.

Configuración del ajuste de rendimiento del comando bq export

Mainframe Connector admite la siguiente configuración de ajuste del rendimiento para el comando bq export:

• exporter_thread_count: (Opcional) Define el número de subprocesos de trabajador. El valor predeterminado es 4.
• max_read_streams: (Opcional) Define el número máximo de flujos de lectura. El valor predeterminado es el mismo que el valor definido en exporter_thread_count.
• order_response: (Opcional) Si asignas el valor "true" a esta marca, el exportador conservará el orden de los resultados de la consulta. Esta marca afecta al rendimiento de la exportación. El valor predeterminado es false.
• max_read_queue: (opcional) Define el número máximo de colas de registros de lectura. El valor predeterminado es el doble del número de subprocesos.
• transcoding_buffer: (Opcional) Define el tamaño del búfer de transcodificación por subproceso en MB. El valor predeterminado es 20 MB.

Ten en cuenta que también puedes probar a 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.

Crear una tabla de BigQuery a partir de un copybook

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

Nota: Esta función no es compatible con el analizador antiguo.

Para ayudarte a probar esta función, el comando bq mk también ofrece un modo de prueba. Este modo te permite previsualizar el 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 copybook que se va a usar para crear la tabla.
• --dry_run: (Opcional) Si está habilitado, el comando solo imprime el comando CREATE TABLE SQL generado sin ejecutarlo. Esta marca tiene el valor "false" de forma predeterminada.
• --tablespec "[PROJECT_ID]:[DATASET].[TABLE]": especifica el ID del proyecto de BigQuery, el conjunto de datos y el nombre de la tabla de destino.
• --encoding: especifica la codificación utilizada para leer el archivo de libro de copias. 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 se admiten en 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.

A continuación, se muestra un ejemplo de cómo puedes usar una consulta bq query parametrizada:

Archivo de consulta

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

A continuación, se muestra 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

Realizar una prueba de funcionamiento del comando gsutil cp

El comando gsutil cp decodifica un archivo QSAM mediante un libro de copias de COBOL y genera un archivo ORC en Cloud Storage. Puedes hacer una prueba de funcionamiento del comando gsutil cp con la marca dry_run y probar los siguientes pasos:

• Analiza un copybook o un archivo de datos de COBOL y comprueba si es compatible con Mainframe Connector.
• Decodifica un archivo QSAM sin escribirlo en Cloud Storage.

Usa el siguiente comando para hacer una prueba de funcionamiento:

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, se mostrará un mensaje de error.

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

Si usa la marca dry_run y la fuente de datos no existe, el comando no devuelve un error. En su lugar, solo comprueba el analizador de copybook y, a continuación, completa la ejecución.

Copiar un archivo de Cloud Storage a tu mainframe

Puedes usar el comando gsutil cp para copiar un archivo de Cloud Storage en 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 en un conjunto de datos de mainframe, especifica el DSN y los requisitos de espacio del archivo que quieras 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 con el siguiente formato. Si el archivo ya existe en tu mainframe, comprueba que añades la marca --replace al comando.

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

Haz los cambios siguientes:

• GCS_URI: el identificador uniforme de recurso (URI) de Cloud Storage del archivo de Cloud Storage. Por ejemplo, gs://bucket/sample.mainframe.dsn.
• DSN: la ubicación de destino del DSN en el mainframe.
• RECFM: 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 entre mayúsculas y minúsculas.
• LRECL: (Opcional) Longitud del registro (LRECL) del archivo. El valor debe ser un número entero >= 0. Si no se especifica LRECL, se supone que el archivo tiene el formato de registro de longitud indefinida (U).
• BLKSIZE: (opcional) Tamaño de bloque del archivo. Si se define como 0, el sistema determinará el tamaño de bloque óptimo. El valor debe ser un número entero igual o superior a 0. Si no especifica ningún valor, el archivo se tratará como un archivo no bloqueado.
• noseek: (Opcional) Incluya este parámetro si quiere mejorar el rendimiento de las descargas. Esta marca tiene el valor "false" de forma predeterminada, es decir, las operaciones de búsqueda 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 del ajuste de rendimiento del comando gsutil cp

Mainframe Connector admite la siguiente configuración de ajuste del rendimiento para el comando gsutil cp.

• Usa la marca --parallelism para definir el número de subprocesos. El valor predeterminado es 1 (un solo subproceso).
• Usa el argumento --maxChunkSize para definir el tamaño máximo de cada fragmento. Cada fragmento tendrá su propio archivo ORC. Aumenta este valor para reducir el número de fragmentos creados, pero ten en cuenta que esto requerirá más memoria durante el proceso de transcodificación. Para obtener más información, consulta Analizar el argumento maxChunkSize. El valor predeterminado es 128 MiB.
• Usa el argumento --preload_chunk_count para definir la cantidad de datos que se van a 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, hemos considerado un archivo grande, por lo que hemos usado 8 hilos para alcanzar la velocidad 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 se reduce la sobrecarga de creación y finalización de objetos de Cloud Storage. En el caso de los archivos pequeños, usar menos hilos y fragmentos más pequeños puede dar mejores resultados.

Analiza el argumento maxChunkSize

La marca maxChunkSize acepta valores en forma de importe y 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 de 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 de métrica: b/kb/mb/gb/tb, para kilobyte, megabyte, gigabyte y terabyte, respectivamente.

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