DBMS_PIPE 패키지(영구 메시징 파이프)

DBMS_PIPE 패키지를 사용하면 동일한 인스턴스의 두 개 이상의 세션이 통신할 수 있습니다.

전용 Exadata 인프라의 Oracle Autonomous AI Database는 Oracle Database 19c에서 사용할 수 있는 핵심 DBMS_PIPE 기능과 확장 기능을 지원합니다.

Oracle Database에서 제공되는 핵심 DBMS_PIPE 기능에 대한 자세한 내용은 Oracle Database 19c PL/SQL Packages and Types Reference의 DBMS_PIPE 또는 Oracle Database 26ai PL/SQL Packages and Types Reference를 참조하십시오.

영구 메시징 파이프에 대한 DBMS_PIPE 개요

파이프 기능에는 외부 서비스 인터페이스, 디버깅, 독립 트랜잭션 및 경보와 같은 여러 잠재적 응용 프로그램이 있습니다.

자율운영 AI 데이터베이스에서 DBMS_PIPE 패키지는 영구 메시징 파이프를 지원하는 확장된 기능을 제공합니다. 자세한 내용은 Oracle Database 19c PL/SQL Packages and Types Reference의 DBMS_PIPE 또는 Oracle Database 26ai PL/SQL Packages and Types Reference를 참조하십시오.

DBMS_PIPE의 영구 메시지:

DBMS_PIPE 제한

DBMS_PIPE 패키지는 서로 다른 문자 집합을 사용하는 데이터베이스 간의 메시지 전송을 지원하지 않습니다. 예를 들어, AL32UTF8을 사용하는 하나의 자율운영 AI 데이터베이스 인스턴스와 WE8MSWIN1252를 사용하는 다른 인스턴스가 있는 경우 이 두 데이터베이스 간에 DBMS_PIPE가 포함된 메시지를 전송할 수 없습니다. 이 경우 두 데이터베이스 간에 DBMS_PIPE가 포함된 메시지를 보내려고 하면 ORA-12704 오류가 발생합니다.

영구 메시징에 대한 DBMS_PIPE 서브 프로그램 요약

이 표에서는 DBMS_PIPE 하위 프로그램을 나열하고 간략하게 설명합니다.

하위 프로그램 설명
CREATE_PIPE 함수 파이프를 작성합니다(개인 파이프에 필요).
GET_CREDENTIAL_NAME 함수 전역 credential_name 변수 값을 반환합니다.
GET_LOCATION_URI 함수 메시지가 클라우드 객체 저장소에 저장될 때 사용할 기본 위치 URI로 사용되는 전역 location_uri 변수 값을 반환합니다.

NEXT_ITEM_TYPE 함수

 버퍼에서 다음 항목의 데이터 유형을 반환합니다.

PACK_MESSAGE 프로시저

 로컬 버퍼에 메시지를 작성합니다.
RECEIVE_MESSAGE 함수 이름이 지정된 파이프에서 로컬 버퍼로 메시지를 복사합니다.

RESET_BUFFER 프로시저

 로컬 버퍼의 내용을 비웁니다.

REMOVE_PIPE 함수

 명명된 파이프를 제거합니다.
SEND_MESSAGE 함수 명명된 파이프에 메시지 보내기: 명명된 파이프가 없는 경우 공용 파이프를 암시적으로 생성합니다.
SET_CREDENTIAL_NAME 프로시저 클라우드 객체 저장소에 저장된 메시지에 대한 기본 인증서로 사용되는 credential_name 변수를 설정합니다.
SET_LOCATION_URI 프로시저 클라우드 객체 저장소에 저장된 메시지에 대한 기본 위치 URI로 사용되는 전역 location_uri 변수를 설정합니다.

UNIQUE_SESSION_NAME 함수

 고유한 세션 이름을 반환합니다.

UNPACK_MESSAGE 프로시저

 버퍼의 다음 항목에 액세스합니다.

CREATE_PIPE 함수

이 함수는 공용(public) 또는 전용(private) 파이프를 명시적으로 생성합니다. private 플래그가 TRUE인 경우 파이프 생성자가 전용 파이프의 소유자로 지정됩니다.

명시적으로 생성된 파이프는 REMOVE_PIPE를 호출하거나 인스턴스를 종료해야만 제거할 수 있습니다.

구문

DBMS_PIPE.CREATE_PIPE (
   pipename     IN VARCHAR2,
   maxpipesize  IN INTEGER DEFAULT 66536,
   private      IN BOOLEAN DEFAULT TRUE)
RETURN INTEGER;

매개변수

매개변수 설명
pipename

작성 중인 파이프의 이름입니다.

SEND_MESSAGE 및 RECEIVE_MESSAGE를 호출할 때 이 이름을 사용해야 합니다. 이 이름은 전체 인스턴스에서 고유해야 합니다.

**주의:** ORA$로 시작하는 파이프 이름은 사용하지 마십시오. 이러한 프로시저는 Oracle에서 제공하는 프로시저에서 사용하도록 예약되어 있습니다. 파이프 이름은 128바이트보다 길지 않아야 하며 대소문자를 구분하지 않습니다. 지금은 이름에 Globalization Support 문자를 포함할 수 없습니다.

maxpipesize

파이프에 허용되는 최대 크기(바이트)입니다.

파이프에 있는 모든 메시지의 총 크기는 이 크기를 초과할 수 없습니다. 이 최대값을 초과하면 메시지가 차단됩니다.

기본 maxpipesize는 66536바이트입니다.

파이프에 대한 maxpipesize는 파이프 특성의 일부가 되며 파이프 수명 동안 지속됩니다. 값이 큰 SEND_MESSAGE 호출자는 maxpipesize를 늘립니다. 값이 작은 호출자는 더 큰 기존 값을 사용합니다.

기본 maxpipesize 65536은 모든 파이프에 적용할 수 있습니다.

private

기본값인 TRUE를 사용하여 전용 파이프를 만듭니다.

공용 파이프는 SEND_MESSAGE를 호출할 때 암시적으로 생성할 수 있습니다.

반환 값

Return 설명
0

성공.

파이프가 이미 있고 파이프를 생성하려는 유저에게 파이프를 사용할 권한이 있는 경우 Oracle은 0을 반환하여 성공을 나타내며 파이프에 이미 있는 모든 데이터는 유지됩니다.
ORA-23322

이름 지정 충돌로 인해 실패했습니다.

동일한 이름의 파이프가 존재하고 다른 유저가 생성한 경우 Oracle은 이름 지정 충돌을 나타내는 오류 ORA-23322를 표시합니다.

예외사항

예외사항 설명
Null pipe name 권한 오류: 동일한 이름의 파이프가 이미 있으며 사용할 수 없습니다.

예

MY_PIPE1라는 명시적 전용(private) 생성

DECLARE
  l_status INTEGER;
BEGIN
  l_status := DBMS_PIPE.create_pipe(
      pipename  => 'MY_PIPE1',
      private   => TRUE);
END;
/

GET_CREDENTIAL_NAME 함수

이 함수는 메시지가 클라우드 객체 저장소에 저장될 때 사용할 전역 credential_name 변수 값을 반환합니다.

구문

DBMS_PIPE.GET_CREDENTIAL_NAME
         RETURN VARCHAR2;

반환 값

반환 값 설명
credential_name 클라우드 오브젝트 스토리지에 액세스할 자격 증명 이름입니다.

예

DECLARE
  credential_name     VARCHAR2(400)
BEGIN
  credential_name := DBMS_PIPE.GET_CREDENTIAL_NAME;
END;
/

GET_LOCATION_URI 함수

이 함수는 파이프 메시지가 클라우드 객체 저장소에 저장될 때 기본 위치 URI로 사용할 수 있는 전역 location_uri 변수 값을 반환합니다.

구문

DBMS_PIPE.GET_LOCATION_URI
        RETURN VARCHAR2;

반환 값

반환 값 설명
location_uri 객체 URI입니다.

예

DECLARE
  location_uri     VARCHAR2(400)
BEGIN
  location_uri := DBMS_PIPE.GET_LOCATION_URI;
END;
/

RECEIVE_MESSAGE 함수

이 기능은 메시지를 로컬 메시지 버퍼에 복사합니다.

구문

DBMS_PIPE.RECEIVE_MESSAGE (
   pipename          IN VARCHAR2,
   timeout           IN INTEGER  DEFAULT maxwait,
   credential_name   IN VARCHAR2 DEFAULT null,
   location_uri      IN VARCHAR2)
RETURN INTEGER;

매개변수

테이블 - RECEIVE_MESSAGE 함수 매개변수

매개변수 설명
pipename

메시지를 수신할 파이프의 이름입니다.

ORA$로 시작하는 이름은 Oracle에서 사용하도록 예약되어 있습니다.

timeout

메시지를 기다리는 시간(초)입니다. 시간 초과 0을 사용하면 차단하지 않고도 읽을 수 있습니다.

시간 초과에는 cache_func 매개변수와 함께 지정된 캐시 함수를 실행하는 데 소요된 시간이 포함되지 않습니다.

기본값: 86400000(1000일)으로 정의된 상수 MAXWAIT입니다.

credential_name

메시지 저장에 사용되는 클라우드 저장소의 인증서 이름입니다.

credential_name는 기본적으로 NULL로 초기화되는 패키지 인수입니다.

DBMS_PIPE.RECEIVE_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

인증서 객체에는 DBMS_PIPE.RECEIVE_MESSAGE를 실행하는 사용자의 EXECUTE 및 READ/WRITE 권한이 있어야 합니다.

location_uri

메시지 저장에 사용되는 클라우드 저장소의 위치 URI입니다.

location_uri는 기본적으로 NULL로 초기화되는 전역 변수입니다.

DBMS_PIPE.RECEIVE_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값은 전역 변수 값보다 우선합니다.

반환 값

테이블 - RECEIVE_MESSAGE 함수 반환 값

Return 설명
0 성공
1 시간 초과됨. 파이프가 암시적으로 생성되어 비어 있으면 제거됩니다.
2 파이프의 레코드가 버퍼에 비해 너무 큽니다.
3 인터럽트가 발생했습니다.
ORA-23322 사용자에게 파이프에서 읽을 수 있는 권한이 부족합니다.

사용법 참고

예외사항

테이블 - RECEIVE_MESSAGE 함수 예외

예외사항 설명
Null pipe name 권한 오류입니다. 파이프에서 레코드를 제거할 수 있는 권한이 부족합니다. 파이프는 다른 사람의 소유입니다.

SEND_MESSAGE 함수

이 함수는 명명된 파이프에 메시지를 전송합니다.

메시지는 PACK_MESSAGE에 대한 호출로 채워진 로컬 메시지 버퍼에 포함됩니다. CREATE_PIPE를 사용하여 파이프를 명시적으로 생성할 수 있습니다. 그렇지 않으면 파이프가 암시적으로 생성됩니다.

구문

DBMS_PIPE.SEND_MESSAGE (
    pipename          IN VARCHAR2,
    timeout           IN INTEGER DEFAULT MAXWAIT,
    credential_name   IN VARCHAR2 DEFAULT null,
    location_uri      IN VARCHAR2 )
RETURN INTEGER;

매개변수

테이블 - SEND_MESSAGE 함수 매개변수

매개변수 설명
credential_name

메시지 저장에 사용되는 클라우드 저장소의 인증서 이름입니다.

credential_name는 기본적으로 NULL로 초기화되는 패키지 인수입니다.

DBMS_PIPE.SEND_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

인증서 객체에는 DBMS_PIPE.SEND_MESSAGE를 실행하는 사용자의 EXECUTE 및 READ/WRITE 권한이 있어야 합니다.

location_uri

메시지 저장에 사용되는 클라우드 저장소의 위치 URI입니다.

location_uri는 기본적으로 NULL로 초기화되는 전역 변수입니다.

DBMS_PIPE.SEND_MESSAGE를 호출하기 전에 이 값을 설정할 수 있습니다. 전달된 매개변수 값이 전역 변수 값보다 우선합니다.

maxpipesize

파이프에 허용되는 최대 크기(바이트)입니다.

파이프에 있는 모든 메시지의 총 크기는 이 크기를 초과할 수 없습니다. 이 최대값을 초과하면 메시지가 차단됩니다. 기본값은 65536바이트입니다.

파이프에 대한 maxpipesize는 파이프 특성의 일부가 되며 파이프 수명 동안 지속됩니다. 값이 큰 SEND_MESSAGE 호출자는 maxpipesize를 늘립니다. 값이 작은 호출자는 단순히 기존의 더 큰 값을 사용합니다.

maxpipesize를 SEND_MESSAGE 프로시저의 일부로 지정하면 파이프를 열기 위한 별도의 호출이 필요하지 않습니다. 파이프를 명시적으로 작성한 경우 선택적 maxpipesize 매개변수를 사용하여 작성 파이프 크기 사양을 재정의할 수 있습니다.

기본 maxpipesize 65536은 모든 파이프에 적용할 수 있습니다.

pipename

메시지를 배치할 파이프의 이름입니다.

명시적 파이프를 사용하는 경우 이 이름은 CREATE_PIPE를 호출할 때 지정한 이름입니다.

**주의:** 'ORA$'로 시작하는 파이프 이름은 사용하지 마십시오. 이러한 이름은 Oracle에서 제공하는 프로시저에서 사용하도록 예약되어 있습니다. 파이프 이름은 128바이트보다 길지 않아야 하며 대소문자를 구분하지 않습니다. 지금은 이름에 Globalization Support 문자를 포함할 수 없습니다.

timeout

파이프에 메시지를 배치하려고 시도하는 동안 대기할 시간(초)입니다.

기본값은 86400000(1000일)으로 정의되는 상수 MAXWAIT입니다.

반환 값

테이블 - SEND_MESSAGE 함수 반환 값

Return 설명
0

성공.

파이프가 이미 있고 파이프를 생성하려는 유저에게 파이프를 사용할 권한이 있는 경우 Oracle은 0을 반환하여 성공을 나타내며 파이프에 이미 있는 모든 데이터는 유지됩니다.

SYSDBS/SYSOPER로 연결된 사용자가 파이프를 재생성하면 Oracle은 상태 0을 반환하지만 파이프 소유권은 변경되지 않습니다.

1

시간 초과됨.

이 절차는 파이프에 대한 잠금을 가져올 수 없거나 파이프가 너무 가득 차서 사용할 수 없기 때문에 시간 초과될 수 있습니다. 파이프가 암시적으로 생성되어 비어 있으면 제거됩니다.
3

인터럽트가 발생했습니다.

파이프가 암시적으로 생성되어 비어 있으면 제거됩니다.
ORA-23322

권한이 부족합니다.

동일한 이름의 파이프가 존재하고 다른 유저가 생성한 경우 Oracle은 이름 지정 충돌을 나타내는 오류 ORA-23322를 표시합니다.

사용법 참고

예외사항

테이블 - SEND_MESSAGE 함수 예외

예외사항 설명
Null pipe name 권한 오류입니다. 파이프에 쓸 수 있는 권한이 부족합니다. 파이프는 개인이며 다른 사람이 소유하고 있습니다.

SET_CREDENTIAL_NAME 프로시저

이 절차에서는 파이프 메시지가 클라우드 객체 저장소에 저장될 때 기본 인증서로 사용되는 credential_name 변수를 설정합니다.

구문

DBMS_PIPE.SET_CREDENTIAL_NAME (
   credential_name   IN VARCHAR2 );

매개변수

매개변수 설명
credential_name 클라우드 오브젝트 스토리지에 액세스할 자격 증명 이름입니다.

사용 노트

Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형에서 일치해야 합니다.

예

BEGIN
     DBMS_PIPE.SET_CREDENTIAL_NAME(
       credential_name =>  'my_cred1');
END;
/

SET_LOCATION_URI 프로시저

이 프로시저는 전역 location_uri 변수를 설정합니다.

구문

DBMS_PIPE.SET_LOCATION_URI (
   location_uri   IN VARCHAR2 );

매개변수

매개변수 설명
location_uri 객체 또는 파일 URI입니다. URI 형식은 사용 중인 클라우드 오브젝트 스토리지 서비스에 따라 달라집니다. 자세한 내용은 클라우드 오브젝트 스토리지 URI 형식을 참조하십시오.

사용 노트

Oracle Cloud Infrastructure Object Storage를 사용하여 메시지를 저장하는 경우 Oracle Cloud Infrastructure 고유 URI 또는 Swift URI를 사용할 수 있습니다. 그러나 위치 URI와 자격 증명은 다음과 같은 유형에서 일치해야 합니다.

예

BEGIN
  DBMS_PIPE.GET_LOCATION_URI(
      location_uri  => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/');
END;
/

관련 콘텐츠