Mainframe Connector API 참조

다음 표에는 Mainframe Connector와 함께 사용할 수 있는 BigQuery, Cloud Storage 및 기타 Google Cloud 명령어가 나와 있습니다.

제품	명령어	설명	원격 트랜스코딩 지원
BigQuery 명령어	`bq export`	이 명령어를 사용하여 바이너리 파일을 만듭니다. 이 명령어에는 COPYBOOK DD를 입력할 수 있습니다. `bq export` 명령어는 일부 성능 조정 기능을 지원합니다. 자세한 내용은 `bq export` 명령어의 성능 개선을 참조하세요. 참고: `bq export` 명령어는 대규모 Bigtable 테이블을 내보내기 위한 요청에 실패합니다. 대규모 테이블을 내보낼 때 오류를 방지하려면 `bq export` 명령어에 `-allowLargeResults` 플래그를 추가합니다.	예
	`bq load`	이 명령어를 사용하여 테이블에 데이터를 로드합니다. 자세한 내용은 bq load를 참조하세요.	없음
	`bq mk`	이 명령어를 사용하여 기본 제공 테이블 또는 외부 테이블과 같이 파티션 나누기 및 클러스터링을 설정해야 하는 BigQuery 리소스를 만듭니다. 자세한 내용은 bq mk를 참조하세요. `bq mk` 명령어를 사용하여 COBOL 카피북 파싱에서 직접 BigQuery 테이블을 생성할 수도 있습니다. 자세한 내용은 카피북에서 BigQuery 테이블 만들기를 참조하세요.	없음
	`bq query`	이 명령어를 사용하여 지정된 SQL 쿼리를 실행하는 쿼리 작업을 만듭니다. 이 명령어는 `--sql` 플래그 또는 QUERY DD에서 SQL 쿼리를 읽습니다. 둘 다 제공되는 경우 `--sql` 플래그의 쿼리가 우선 적용됩니다. `--follow=true` 플래그를 사용하여 선택한 쿼리의 결과를 표시하는 보고서를 생성합니다. 이 보고서를 메인프레임의 파일에 쓰려면 감사 로그 보고서가 포함되어야 하는 파일을 가리키는 DD 문 `AUDITL`을 정의합니다. 정상적인 로깅 동작을 원하는 경우 `--follow` 플래그를 사용하지 마세요. 일부 쿼리 결과는 수백만 개에 달하는 많은 행을 반환할 수 있습니다. 출력을 사람이 읽을 수 있도록 표시되는 줄 수에 제한이 있습니다. 표시되는 행 수를 제어하려면 `--report_row_limit` 플래그를 사용합니다. 예를 들어 `--report_row_limit 10`을 사용하여 결과를 10줄로 제한합니다. 기본적으로 표시되는 줄 수는 30개로 제한됩니다. `bq query` 파라미터화를 사용하려면 bq 쿼리 파라미터화를 참조하세요. 자세한 내용은 bq query를 참조하세요.	예
	`bq rm`	BigQuery 리소스를 영구적으로 삭제하려면 이 명령어를 사용합니다. 이 명령어는 리소스를 영구 삭제하므로 주의해서 사용하는 것이 좋습니다. 자세한 내용은 bq rm을 참조하세요.	없음
Cloud Storage 명령어	`scp`	Cloud Storage에 텍스트 또는 바이너리 데이터를 복사하려면 이 명령어를 사용합니다. 단순 바이너리 복사 모드를 사용하여 데이터세트를 IBM z/OS의 데이터세트를 데이터 파이프라인의 일부로 수정되지 않은 Cloud Storage로 복사할 수 있습니다. 원하는 경우 문자 인코딩을 확장 바이너리 코딩 십진수 교환 코드(EBCDIC)에서 ASCII UTF-8로 변환하고 줄바꿈을 추가할 수 있습니다. 이 명령어를 사용하여 작업 제어 언어(JCL)에 정의된 애플리케이션 소스 코드를 복사할 수도 있습니다.	없음
`gsutil` 유틸리티	`gsutil cp`	이 명령어를 사용하여 데이터 세트를 트랜스코딩하고 최적화된 행 열 형식(ORC) 파일 형식으로 Cloud Storage에 씁니다. 이 명령어는 INFILE DD에서 데이터를 읽고 COPYBOOK 파일에서 레코드 레이아웃을 읽습니다. 명령어에서 데이터 소스 이름(DSN) 파일의 데이터를 읽으려면 다음 플래그를 사용합니다. `--inDsn`: 입력 데이터 세트 DSN입니다. 이 플래그가 제공되면 INFILE DD가 재정의됩니다. `--cobDsn`: 카피북 DSN입니다. 이 플래그를 제공하면 COPYBOOK DD가 재정의됩니다. 그런 다음 이 명령어는 Cloud Storage API에 대한 구성 가능한 수의 동시 연결을 열고 COBOL 데이터 세트를 열 형식 및 GZIP 압축 ORC 파일 형식으로 트랜스코딩합니다. 약 35%의 압축률을 예상할 수 있습니다. 원하는 경우 이 명령어를 사용하여 메인프레임의 VM에서 실행 중인 Mainframe Connector gRPC 서비스와 상호작용할 수 있습니다. 이렇게 하려면 `SRVHOST` 및 `SRVPORT` 환경 변수를 설정하거나 명령줄 옵션을 사용하여 호스트 이름과 포트 번호를 제공합니다. gRPC 서비스를 사용하면 먼저 Mainframe Connector가 입력 데이터 세트를 Cloud Storage에 복사한 다음 리모트 프로시져(RPC) 호출을 통해 gRPC 서비스에 파일 트랜스코딩을 지시합니다. `gsutil cp` 명령어를 사용하여 다음 작업을 할 수도 있습니다. Cloud Storage에서 메인프레임으로 파일 복사 `gsutil cp` 명령어의 성능 미세 조정	예
	`gsutil rm`	버킷이나 버킷 내에서 객체를 삭제하려면 이 명령어를 사용합니다. 자세한 내용은 rm - Remove objects를 참조하세요.	없음
`gszutil` 유틸리티	`gszutil`	`gszutil` 유틸리티는 IBM JZOS Java SDK를 사용하여 실행되며 JCL을 사용하는 `gsutil` 및 BigQuery 명령줄 호출을 허용하는 셸 에뮬레이터를 제공합니다. `gszutil` 유틸리티는 COPYBOOK DD 형식으로 스키마를 수락하여 `gsutil` 유틸리티의 기능을 확장합니다. Cloud Storage에 업로드하기 전에 COBOL 데이터 세트를 ORC로 직접 트랜스코딩하는 데 사용합니다. 또한 `gszutil` 유틸리티를 사용하면 JCL을 사용하여 BigQuery `query` 및 `load`를 실행할 수 있습니다. `gszutil` 유틸리티는 gRPC 서버와 함께 작동하여 MIPS(초당 백만 명령) 소비를 줄이는 데 도움이 됩니다. 프로덕션 환경에서 `gszutil` 유틸리티를 사용하여 Cloud Storage의 바이너리 파일을 ORC 형식으로 변환하는 것이 좋습니다.	없음
기타 명령어	`gcloud pubsub topics send`	이 명령어를 사용하여 Pub/Sub 주제에 메시지를 보냅니다. 명령줄이나 데이터 세트를 사용하여 메시지를 제공할 수 있습니다.	없음
	`gcloud dataflow flex-template run`	이 명령어를 사용하여 Dataflow Flex 템플릿 실행을 트리거합니다. 이 명령어는 지정된 Flex 템플릿 경로에서 작업을 실행합니다. 자세한 내용은 gcloud dataflow flex-template run을 참조하세요.	없음
	`curl`	웹 서비스 또는 REST API에 HTTP 요청을 보내려면 이 명령어를 사용합니다.	없음
	`systemreport`	이 명령어를 사용하여 필요한 시스템 데이터를 표준 출력(stdout)에 출력합니다. 이를 통해 Mainframe Connector 지원팀은 광범위한 고객 상호작용 없이도 문제를 진단하는 데 필요한 정보를 수집할 수 있습니다. `systemreport` 명령어는 사용하는 플래그에 따라 다음과 같은 시스템 데이터를 출력합니다. `--supported_ciphers`: 지원되는 암호화 `--available_security_providers`: 사용 가능한 보안 제공업체	없음

`bq export` 명령어의 성능 조정 구성

Mainframe Connector는 bq export 명령어에 다음과 같은 성능 조정 구성을 지원합니다.

exporter_thread_count: (선택사항) 작업자 스레드 수를 설정합니다. 기본값은 4입니다.
max_read_streams: (선택사항) 최대 읽기 스트림을 설정합니다. 기본값은 exporter_thread_count에 설정된 값과 동일합니다.
order_response: (선택사항) 이 플래그를 true로 설정하면 내보내기 도구가 쿼리 결과 순서를 유지합니다. 이 플래그는 내보내기 성능에 영향을 미칩니다. 기본값은 false입니다.
max_read_queue: (선택사항) 읽기 레코드 큐의 최대 개수를 설정합니다. 기본값은 스레드 수의 두 배입니다.
transcoding_buffer: (선택사항) 스레드당 트랜스코딩 버퍼의 크기(MB)를 설정합니다. 기본값은 20MB입니다.

성능을 개선하기 위해 OVERRIDE_GRPC_WINDOW_MB 환경 변수를 설정하여 전송 기간 크기를 늘려 볼 수도 있습니다. 기본 기간 크기는 4MB입니다.

카피북에서 BigQuery 테이블 만들기

bq mk 명령어를 사용하여 COBOL 카피북 파싱에서 직접 BigQuery 테이블을 생성할 수 있습니다. 네이티브 카피북 파서는 카피북 내의 VALUE 절에서 기본값을 추출하고 새로 만든 BigQuery 테이블의 해당 열에 할당합니다.

이 기능을 테스트하는 데 도움이 되도록 bq mk 명령어는 테스트 실행 모드도 제공합니다. 이 모드를 사용하면 BigQuery에서 실제로 테이블을 만들지 않고도 생성된 CREATE TABLE SQL 명령어를 미리 볼 수 있습니다.

bq mk 명령어는 이 기능을 지원하기 위해 다음과 같은 구성 옵션을 제공합니다.

--schema_from_copybook: 테이블을 만드는 데 사용할 카피북을 지정합니다.
--dry_run: (선택사항) 사용 설정하면 이 명령어는 생성된 CREATE TABLE SQL 명령어를 실행하지 않고 출력만 합니다. 이 플래그는 기본적으로 false로 설정됩니다.
--tablespec "[PROJECT_ID]:[DATASET].[TABLE]": 대상 테이블의 BigQuery 프로젝트 ID, 데이터 세트, 테이블 이름을 지정합니다.
--encoding: 카피북 파일을 읽는 데 사용되는 인코딩을 지정합니다. 기본값은 CP037입니다.

다음 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  "     "

HIGH-VALUE 및 LOW-VALUE 절은 영숫자 변수에만 지원됩니다.

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>

`bq query` 파라미터화

Mainframe Connector를 사용하면 bq query와 함께 파라미터화된 쿼리를 사용할 수 있습니다.

다음은 파라미터화된 bq query 쿼리를 사용하는 방법의 예시입니다.

쿼리 파일

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

다음은 여러 파라미터가 있는 예시입니다.

쿼리 파일

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

실행 예시

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

Cloud Storage에서 메인프레임으로 파일 복사

gsutil cp 명령어를 사용하여 Cloud Storage에서 메인프레임 데이터 세트로 파일을 복사할 수 있습니다. 파티션을 나눈 데이터 세트(PDS)는 복사할 수 없습니다.

Cloud Storage에서 메인프레임 데이터 세트로 파일을 복사하려면 다음 예시와 같이 JCL에서 메인프레임에 다운로드할 파일의 DSN 및 공간 요구사항을 지정합니다.

//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 *

다음 형식으로 gsutil cp 명령어를 지정합니다. 메인프레임에 이미 파일이 있는 경우 명령어에 --replace 플래그를 추가해야 합니다.

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

다음을 바꿉니다.

GCS_URI: Cloud Storage 파일의 Cloud Storage 통합 리소스 식별자(URI)입니다. 예를 들면 gs://bucket/sample.mainframe.dsn입니다.
DSN: 메인프레임의 DSN 대상 위치입니다.
RECFM: 메인프레임 파일의 레코드 형식(RECFM)입니다. 유효한 값은 F, FB, U입니다. 이러한 값은 대소문자를 구분하지 않습니다.
LRECL: (선택사항) 파일의 레코드 길이(LRECL)입니다. 값은 0보다 크거나 같은 정수여야 합니다. LRECL이 지정되지 않으면 파일이 정의되지 않은 길이 레코드 형식(U)으로 간주됩니다.
BLKSIZE: (선택사항) 파일의 블록 크기입니다. 0으로 설정하면 시스템에서 최적의 블록 크기를 결정합니다. 값은 0보다 크거나 같은 정수여야 합니다. 값을 지정하지 않으면 파일이 차단되지 않은 파일로 취급됩니다.
noseek: (선택사항) 다운로드 성능을 개선하려면 이 파라미터를 포함하세요. 이 플래그는 기본적으로 false로 설정됩니다. 즉, 탐색 작업이 사용 설정됩니다.

실행 예시

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

`gsutil cp` 명령어의 성능 조정 구성

Mainframe Connector는 gsutil cp 명령어에 대해 다음과 같은 성능 조정 구성을 지원합니다.

--parallelism 플래그를 사용하여 스레드 수를 설정합니다. 기본값은 1(단일 스레드)입니다.
--maxChunkSize 인수를 사용하여 각 청크의 최대 크기를 설정합니다. 각 청크에는 자체적인 최적화된 행 열 형식(ORC) 파일이 있습니다. 트랜스코딩 프로세스 중에 더 큰 메모리가 요구되는 대신 생성되는 청크 수를 줄이려면 이 값을 늘립니다. 자세한 내용은 maxChunkSize 인수 파싱을 참조하세요. 기본값은 128MiB입니다.
모든 작업자가 사용 중일 때 --preload_chunk_count 인수를 사용하여 메모리에 미리 로드할 데이터 양을 설정합니다. 이 인수는 메모리 비용으로 성능을 향상시킬 수 있습니다. 기본값은 2입니다.

실행 예시

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

이 예시에서는 대용량 파일을 고려했으므로 회선 속도에 도달하는 8개의 스레드를 사용했습니다. 메모리가 충분한 경우 오버헤드 생성 및 Cloud Storage 객체 완료를 줄여주므로 단위 크기를 256MiB 또는 512MiB로 늘리는 것이 좋습니다. 스레드와 청크를 적게 사용하는 작은 파일의 경우 더 나은 결과를 얻을 수 있습니다.

`maxChunkSize` 인수 파싱

maxChunkSize 플래그는 금액과 측정 단위 형식의 값을 허용합니다(예: 5MiB). 양과 크기 사이에 공백을 사용할 수 있습니다.

값은 다음 형식으로 제공할 수 있습니다.

Java 형식: b/k/m/g/t(각각 바이트, 키비바이트, 메비바이트, 기비바이트, 테비바이트)
국제 형식: KiB/MiB/GiB/TiB(각각 키비바이트, 메비바이트, 기비바이트, 테비바이트)
측정항목 형식: b/kb/mb/gb/tb(각각 킬로바이트, 메가바이트, 기가바이트, 테라바이트)

데이터 크기 파싱은 대소문자를 구분하지 않습니다. 양의 일부분은 지정할 수 없습니다. 예를 들어 0.7MiB 대신 716KiB를 사용합니다.

Mainframe Connector API 참조

`bq export`

`bq load`

`bq mk`

`bq query`

`bq rm`

`scp`

`gsutil cp`

`gsutil rm`

`gszutil`

`gcloud pubsub topics send`

`gcloud dataflow flex-template run`

`curl`

`systemreport`

`bq export` 명령어의 성능 조정 구성

카피북에서 BigQuery 테이블 만들기

`bq query` 파라미터화

Cloud Storage에서 메인프레임으로 파일 복사

`gsutil cp` 명령어의 성능 조정 구성

`maxChunkSize` 인수 파싱

Mainframe Connector API 참조

bq export

bq load

bq mk

bq query

bq rm

scp

gsutil cp

gsutil rm

gszutil

gcloud pubsub topics send

gcloud dataflow flex-template run

curl

systemreport

bq export 명령어의 성능 조정 구성

카피북에서 BigQuery 테이블 만들기

bq query 파라미터화

Cloud Storage에서 메인프레임으로 파일 복사

gsutil cp 명령어의 성능 조정 구성

maxChunkSize 인수 파싱

`bq export`

`bq load`

`bq mk`

`bq query`

`bq rm`

`scp`

`gsutil cp`

`gsutil rm`

`gszutil`

`gcloud pubsub topics send`

`gcloud dataflow flex-template run`

`curl`

`systemreport`

`bq export` 명령어의 성능 조정 구성

`bq query` 파라미터화

`gsutil cp` 명령어의 성능 조정 구성

`maxChunkSize` 인수 파싱