Mainframe Connector API 참조

다음 표에는 메인프레임 커넥터와 함께 사용할 수 있는 BigQuery, Cloud Storage, 기타 Google Cloud 명령어가 나와 있습니다.

제품 명령어 설명 원격 트랜스코딩 지원
BigQuery 명령어 이 명령어를 사용하여 바이너리 파일을 만듭니다. 이 명령어에는 COPYBOOK DD를 입력할 수 있습니다.

bq export 명령어는 일부 성능 조정 기능을 지원합니다. 자세한 내용은 bq export 명령어의 성능 개선을 참조하세요.

bq export 명령어를 사용하여 맞춤설정된 문자 집합을 사용할 수 있습니다. 자세한 내용은 맞춤설정된 문자 집합 사용을 참고하세요.

참고: bq export 명령어는 대규모 Bigtable 테이블을 내보내기 위한 요청에 실패합니다. 대규모 테이블을 내보낼 때 오류를 방지하려면 bq export 명령어에 -allowLargeResults 플래그를 추가합니다.
이 명령어를 사용하여 테이블에 데이터를 로드합니다. 자세한 내용은 bq load를 참고하세요. 없음
이 명령어를 사용하여 설정할 때 파티셔닝 및 클러스터링이 필요한 BigQuery 리소스(예: 기본 제공 테이블 또는 외부 테이블)를 만듭니다. 자세한 내용은 bq mk를 참조하세요.

bq mk 명령어를 사용하여 COBOL 카피북 파싱에서 직접 BigQuery 테이블을 생성할 수도 있습니다. 자세한 내용은 카피북에서 BigQuery 테이블 만들기를 참조하세요.
없음
이 명령어를 사용하여 지정된 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를 참조하세요.
이 명령어를 사용하여 BigQuery 리소스를 영구적으로 삭제합니다. 이 명령어는 리소스를 영구 삭제하므로 주의해서 사용하는 것이 좋습니다. 자세한 내용은 bq rm을 참고하세요. 없음
Cloud Storage 명령어 이 명령어를 사용하여 텍스트 또는 바이너리 데이터를 Cloud Storage로 복사합니다. 간단한 바이너리 복사 모드를 사용하여 데이터 파이프라인의 일부로 IBM z/OS에서 Cloud Storage로 데이터 세트를 수정되지 않은 상태로 복사할 수 있습니다. 원하는 경우 문자 인코딩을 확장 바이너리 코딩 십진수 교환 코드(EBCDIC)에서 ASCII UTF-8로 변환하고 줄바꿈을 추가할 수 있습니다.

이 명령어를 사용하여 작업 제어 언어(JCL)에 정의된 애플리케이션 소스 코드를 복사할 수도 있습니다.
없음
gsutil 유틸리티 이 명령어를 사용하여 데이터 세트를 트랜스코딩하고 최적화된 행 열 형식(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 서비스와 상호작용할 수 있습니다. 이렇게 하려면 SRVHOSTSRVPORT 환경 변수를 설정하거나 명령줄 옵션을 사용하여 호스트 이름과 포트 번호를 제공합니다. gRPC 서비스를 사용하면 먼저 Mainframe Connector가 입력 데이터 세트를 Cloud Storage에 복사한 다음 리모트 프로시져(RPC) 호출을 통해 gRPC 서비스에 파일 트랜스코딩을 지시합니다.

gsutil cp 명령어를 사용하여 다음 작업을 수행할 수도 있습니다.
이 명령어를 사용하여 버킷 또는 버킷 내의 객체를 삭제합니다. 자세한 내용은 rm - 객체 삭제를 참고하세요. 없음
gszutil 유틸리티 gszutil 유틸리티는 IBM JZOS Java SDK를 사용하여 실행되며 JCL을 사용하여 gsutil 및 BigQuery 명령줄 호출을 허용하는 셸 에뮬레이터를 제공합니다.

gszutil 유틸리티는 COPYBOOK DD 형식으로 스키마를 수락하여 gsutil 유틸리티의 기능을 확장합니다. Cloud Storage에 업로드하기 전에 COBOL 데이터 세트를 ORC로 직접 트랜스코딩하는 데 사용합니다. gszutil 유틸리티를 사용하면 JCL을 사용하여 BigQuery queryload를 실행할 수도 있습니다.

gszutil 유틸리티는 gRPC 서버와 함께 작동하여 MIPS(초당 백만 명령) 소비를 줄이는 데 도움이 됩니다. 프로덕션 환경에서 gszutil 유틸리티를 사용하여 Cloud Storage의 바이너리 파일을 ORC 형식으로 변환하는 것이 좋습니다.
없음
기타 명령어 이 명령어를 사용하여 Pub/Sub 주제에 메시지를 전송합니다. 명령줄을 사용하거나 데이터 세트를 사용하여 메시지를 제공할 수 있습니다. 없음
이 명령어를 사용하여 Dataflow flex 템플릿 실행을 트리거합니다. 이 명령어는 지정된 Flex 템플릿 경로에서 작업을 실행합니다. 자세한 내용은 gcloud dataflow flex-template run을 참고하세요. 없음
이 명령어를 사용하여 웹 서비스 또는 REST API에 HTTP 요청을 보냅니다. 없음
이 명령어를 사용하여 필요한 시스템 데이터를 표준 출력(stdout)에 출력합니다. 이를 통해 Mainframe Connector 지원팀은 광범위한 고객 상호작용 없이도 문제를 진단하는 데 필요한 정보를 수집할 수 있습니다.
systemreport 명령어는 사용하는 플래그에 따라 다음과 같은 시스템 데이터를 출력합니다.
  • --supported_ciphers: 지원되는 암호화
  • --available_security_providers: 사용 가능한 보안 제공업체
아니요

맞춤설정된 문자 집합 사용

Mainframe Connector는 바이트를 BigQuery 문자열로 디코딩하는 다양한 문자 집합을 지원하며 그 반대의 경우도 마찬가지입니다. Mainframe Connector를 사용하면 맞춤설정된 문자 집합을 구성할 수 있습니다. Unicode 문자 매핑 (UCM) 파일을 빌드하여 맞춤설정된 문자 집합을 구성할 수 있습니다. Mainframe Connector는 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

맞춤설정된 문자 집합을 사용하려면 UCM 형식으로 구성 파일을 정의합니다. --encoding=charset 플래그를 설정하여 gsutil cp 또는 bq export 명령어와 함께 이 맞춤설정된 문자 집합을 사용할 수 있습니다.

맞춤설정된 문자 집합을 만들 때는 다음을 확인하세요.

  • UCM 파일을 정의할 때는 다음 사항에 유의하세요.
    • 메인프레임 커넥터는 단일 바이트 문자 집합 (SBCS)을 사용하는 맞춤설정된 문자 집합만 지원합니다.
    • Mainframe Connector는 UCM 정밀도 표시기 |0만 지원합니다.
    • UCM 파일이 다중 가상 저장소 파티션화된 데이터 세트 (MVS PDS)가 아닌 z/OS Unix 시스템 서비스 (USS)에 있는지 확인합니다.
    • UCM 파일이 확장 바이너리 코딩 십진수 교환 코드 (EBCDIC) 형식이 아닌 American Standard Code for Information Interchange (ASCII) 형식으로 저장되어 있는지 확인합니다.
  • 가능한 모든 단일 바이트 값을 유니코드 문자로 명시적으로 매핑합니다. 바이트가 매핑될 유니코드 문자를 잘 모르겠다면 U+FFFD에 매핑하는 것이 좋습니다. 서로 다른 바이트 시퀀스를 동일한 유니코드 문자로 매핑할 수 있습니다. 그러나 이 경우 매핑은 양방향이 아닙니다. 즉, 데이터를 BigQuery로 로드한 후 나중에 바이너리 파일로 다시 내보내면 출력이 원래 입력과 다를 수 있습니다.
  • 두 번째 열의 바이트 시퀀스가 고유한지 확인합니다. 여러 바이트 시퀀스가 동일한 유니코드 문자로 매핑되는 경우 이 유니코드 문자는 UCM 파일에서 마지막으로 정의된 매핑의 바이트 시퀀스로 디코딩됩니다.
  • 환경 변수 BQSH_FEATURE_CUSTOM_CHARSET를 UCM 파일의 경로로 설정하여 메인프레임 커넥터가 UCM 파일을 찾을 수 있는지 확인합니다. 여러 문자 집합을 사용하려면 세미콜론 구분자로 구분된 여러 문자 집합의 경로를 제공하면 됩니다. 예를 들면 BQSH_FEATURE_CUSTOM_CHARSET=path1;path2입니다. path는 로컬 파일 또는 Cloud Storage에 저장된 파일을 가리킬 수 있습니다. --remote 플래그와 함께 gsutil cp 또는 bq export 명령어를 실행하여 원격 트랜스코딩을 실행하는 경우 Mainframe Connector는 BQSH_FEATURE_CUSTOM_CHARSET 환경 변수에 설정된 로컬 값을 사용합니다. 독립형 모드에서 Mainframe Connector를 실행할 때도 마찬가지입니다. --encoding 플래그가 BQSH_FEATURE_CUSTOM_CHARSET에 설정한 값과 일치하지 않는 맞춤설정된 문자 집합을 참조하거나 BQSH_FEATURE_CUSTOM_CHARSET를 전혀 설정하지 않은 경우 명령어가 오류 메시지와 함께 종료됩니다.

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-VALUELOW-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

gsutil cp 명령어의 연습 실행 수행

gsutil cp 명령어는 COBOL 카피북을 사용하여 큐에 추가된 순차 액세스 메서드(QSAM) 파일을 디코딩하고 Cloud Storage에 ORC 파일을 생성합니다. dry_run 플래그를 사용하여 gsutil cp 명령어의 테스트 실행을 실행하고 다음 단계를 테스트할 수 있습니다.

  • COBOL 카피북 또는 데이터 파일을 파싱하고 메인프레임 커넥터와 호환되는지 확인합니다.
  • QSAM 파일을 Cloud Storage에 쓰지 않고 디코딩합니다.

다음 명령어를 사용하여 시험 이전을 실행합니다.

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

모든 단계가 성공적으로 실행되면 명령어가 반환 코드 0으로 종료됩니다. 문제가 발생하면 오류 메시지가 표시됩니다.

dry_run 플래그를 사용하면 읽은 총 바이트 수, 기록된 레코드 수, 총 오류 수와 같은 모든 통계가 로깅됩니다.

dry_run 플래그를 사용하고 데이터 소스가 없는 경우 명령어는 오류를 반환하지 않습니다. 대신 Copybook 파서만 확인한 후 실행을 완료합니다.

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개의 스레드를 사용했습니다. 메모리가 충분한 경우 청크 크기를 256MiB 또는 512MiB로 늘리는 것이 좋습니다. 이렇게 하면 Cloud Storage 객체를 만들고 완료하는 오버헤드가 줄어듭니다. 작은 파일의 경우 스레드와 청크를 적게 사용하면 더 나은 결과를 얻을 수 있습니다.

maxChunkSize 인수 파싱

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

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

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

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