Summary of Share Producer Subprograms
This table lists the DBMS_SHARE
package procedures and
functions used to produce shares for recipients.
Subprogram | Description |
---|---|
ADD_TO_SHARE Procedure | Add a table or view to a share. |
ASSERT_SHAREABLE_OBJECT Procedure | Return without error, if the object exists and can be shared. |
ASSERT_SHARING_ID Procedure | Run basic validation checks against a sharing id and return one in canonical form. |
CAN_CREATE_SHARE Function | This function checks to see if the current schema can create share recipients. |
CAN_CREATE_SHARE_RECIPIENT Function | This function checks to see if the current schema can create share recipients. |
CLEAR_RECIPIENT_EVENTS Procedure | Clear events from the share recipient event log. |
CLEAR_SHARE_EVENTS Procedure | Clear events from the share event log. |
CREATE_BEARER_TOKEN_CREDENTIAL Procedure | Create a credential suitable for use with delta share providers. |
CREATE_CLOUD_STORAGE_LINK Procedure | Create a named cloud storage URI link. |
CREATE_OR_REPLACE_CLOUD_STORAGE_LINK Procedure | Create or replace a named cloud storage URI. |
CREATE_OR_REPLACE_SHARE_RECIPIENT Procedure | Create or replace a share recipient. |
CREATE_SHARE Procedure | Create a named share object. |
CREATE_SHARE_RECIPIENT Procedure | Create a new share recipient. |
DROP_CLOUD_STORAGE_LINK Procedure | Drop a cloud storage link. |
DROP_RECIPIENT Procedure | Drop a recipient. |
DROP_SHARE Procedure | Drop a share and all of its contents. |
DROP_SHARE_LINK_VIEW Procedure | Drop a view that was created by
the CREATE_SHARE_LINK_VIEW procedure.
|
DROP_SHARE_VERSION Procedure | Drop a single share version. |
DROP_SHARE_VERSIONS Procedure | Drop a range of share versions. |
DROP_UNUSED_SHARE_VERSIONS Procedure | Drop any share version that is not currently in use. |
ENABLE_SCHEMA Procedure | Enable or disable a schema for sharing. |
GET_ACTIVATION_LINK Function | Generate the link that gets put into emails to the authorized recipient. |
GET_PUBLISHED_IDENTITY Function | Get data about the current user
that was set by SET_PUBLISHED_IDENTITY .
|
GET_RECIPIENT_PROPERTY Function | Return the value of a property for a recipient. |
GET_SHARE_PROPERTY Function | Get the property value of an existing share. |
GET_SHARE_TABLE_PROPERTY Function | Get the property value of an existing share table. |
GRANT_TO_RECIPIENT Procedure | Grant access on a share to a specific recipient. |
POPULATE_SHARE_PROFILE Procedure | Generate a delta profile for a recipient. |
PUBLISH_SHARE Procedure | Publish a share and return immediately. |
PUBLISH_SHARE_WAIT Procedure | Publish a share and wait until the background job is complete. |
PURGE_DETACHED_FILES Procedure | Delete or forget parquet files that have become detached from their shares. |
REMOVE_FROM_SHARE Procedure | Remove a table or view from a share. |
RENAME_RECIPIENT Procedure | Rename a recipient. |
RENAME_SHARE Procedure | Rename a share. |
RENAME_SHARE_LINK Procedure | Rename a registered share link. |
RENAME_SHARE_SCHEMA Procedure | Rename a share schema. |
RENAME_SHARE_TABLE Procedure | Rename a share table. |
REVOKE_FROM_RECIPIENT Procedure | Revoke access on a share from a specific recipient. |
SET_CURRENT_SHARE_VERSION Procedure | Change the current version of a share. |
SET_PUBLISHED_IDENTITY Procedure | Set data about the current user that will be supplied to recipients of published ORACLE shares. |
SET_RECIPIENT_LOG_LEVEL Procedure | Change the log level for an existing share recipient. |
SET_SHARE_LOG_LEVEL Procedure | Change the log level for an existing share. |
SET_STORAGE_CREDENTIAL Procedure | Set the access credential name for the given storage. |
STOP_JOB Procedure | Stop a running share job. |
UNPUBLISH_SHARE Procedure | Unpublish a share. |
UPDATE_DEFAULT_RECIPIENT_PROPERTY Procedure | Update the default recipient property values. |
UPDATE_DEFAULT_SHARE_PROPERTY Procedure | Update the default share property values. |
UPDATE_RECIPIENT_PROPERTY Procedure | Update a property of an existing recipient. |
UPDATE_SHARE_JOB_PROPERTY Procedure | Modify properties of a running share job. |
UPDATE_SHARE_PROPERTY Procedure | Update a property of an existing share. |
UPDATE_SHARE_TABLE_PROPERTY Procedure | Update the property value of an existing share table. |
VALIDATE_CREDENTIAL Function | Validate a credential name, converting it to canonical form first if required. |
VALIDATE_SHARE_STORAGE Procedure | Check to see if the given storage is suitable for versioned shares. |
WAIT_FOR_JOB Procedure | This procedure waits until the specified share job is complete. |
- ADD_TO_SHARE Procedure
Add a table or view to a share. The object becomes visible to any external user who has been granted access to the share. - ASSERT_SHAREABLE_OBJECT Procedure
Return without error, if the object exists and can be shared. - ASSERT_SHARING_ID Procedure
Run basic validation checks against a sharing id and return one in canonical form. An exception is raised if the id is obviously invalid. - CAN_CREATE_SHARE Function
This function checks to see if the current schema can create share recipients. If shares can be created, a 1 is returned and 0 otherwise. - CAN_CREATE_SHARE_RECIPIENT Function
This function checks to see if the current schema can create share recipients. If shares can be created a 1 is returned, and 0 otherwise. - CLEAR_RECIPIENT_EVENTS Procedure
Clear events from the share recipient event log. - CLEAR_SHARE_EVENTS Procedure
Clear events from the share event log. - CREATE_BEARER_TOKEN_CREDENTIAL Procedure
Create a credential suitable for use with delta share providers. - CREATE_CLOUD_STORAGE_LINK Procedure
Create a named cloud storage URI link. A cloud storage link is a named association between an OCI bucket URI, and a local credential name. - CREATE_OR_REPLACE_CLOUD_STORAGE_LINK Procedure
Create or replace a named cloud storage URI. A cloud storage link is a named association between an OCI bucket URI, and a local credential name. - CREATE_OR_REPLACE_SHARE_RECIPIENT Procedure
Create or replace a share recipient. You must provide at least an email address or sharing id. - CREATE_SHARE Procedure
Create a named share object. - CREATE_SHARE_RECIPIENT Procedure
Create a new share recipient. - DROP_CLOUD_STORAGE_LINK Procedure
Drop a cloud storage link. - DROP_RECIPIENT Procedure
Drop a recipient. All access to the recipient will be revoked. - DROP_SHARE Procedure
Drop a share and all of its contents. Future access to the share by consumers will end. - DROP_SHARE_LINK_VIEW Procedure
Drop a view that was created by theCREATE_SHARE_LINK_VIEW
procedure. - DROP_SHARE_VERSION Procedure
Drop a single share version. Note that you cannot drop the current version. - DROP_SHARE_VERSIONS Procedure
Drop a range of share versions. Note that you cannot drop the current version using this procedure. - DROP_UNUSED_SHARE_VERSIONS Procedure
Drop any share version that is not currently in use. - ENABLE_SCHEMA Procedure
Enable or disable a schema for sharing. This procedure must be run by the ADMIN user. - GET_ACTIVATION_LINK Function
Generate the link that gets put into emails to the authorized recipient. This activation link leads to the download page, where the recipient clicks a button to get the delta profile. - GET_PUBLISHED_IDENTITY Function
Get data about the current user that was set bySET_PUBLISHED_IDENTITY
. - GET_RECIPIENT_PROPERTY Function
Return the value of a property for a recipient. - GET_SHARE_PROPERTY Function
Get the property value of an existing share. - GET_SHARE_TABLE_PROPERTY Function
Get the property value of an existing share table. - GRANT_TO_RECIPIENT Procedure
Grant access on a share to a specific recipient. The share and recipient must both belong to the same schema. - POPULATE_SHARE_PROFILE Procedure
Generate a delta profile for a recipient. You could print this to the screen or upload it somewhere. For example, to an object bucket usingDBMS_CLOUD.EXPORT_DATA
. - PUBLISH_SHARE Procedure
Publish a share and return immediately. - PUBLISH_SHARE_WAIT Procedure
Publish a share and wait until the background job is complete. The publication continues even if the call is interrupted. - PURGE_DETACHED_FILES Procedure
Delete or forget parquet files that have become detached from their shares. - REMOVE_FROM_SHARE Procedure
Remove a table or view from a share. - RENAME_RECIPIENT Procedure
Rename a recipient. This procedure only changes the local name of the recipient. The external definition of the recipient, for example the name of the OAUTH user or sharing id, is not changed. - RENAME_SHARE Procedure
Rename a share. Care should be take with this procedure since the change effects any existing consumers whose access is based on the previous name. Consumers are not notified directly or updated. - RENAME_SHARE_LINK Procedure
Rename a registered share link. - RENAME_SHARE_SCHEMA Procedure
Rename a share schema. - RENAME_SHARE_TABLE Procedure
Rename a share table. - REVOKE_FROM_RECIPIENT Procedure
Revoke access on a share from a specific recipient. - SET_CURRENT_SHARE_VERSION Procedure
Change the current version of a share. - SET_PUBLISHED_IDENTITY Procedure
Set data about the current user that will be supplied to recipients of published ORACLE shares. - SET_RECIPIENT_LOG_LEVEL Procedure
Change the log level for an existing share recipient. - SET_SHARE_LOG_LEVEL Procedure
Change the log level for an existing share. - SET_STORAGE_CREDENTIAL Procedure
Set the credential name used by the current user when it attempts to access the given storage. - STOP_JOB Procedure
Attempt to stop a running share job. The procedure should return quickly, but it may take some time for the associated job to stop. - UNPUBLISH_SHARE Procedure
Unpublish a share. - UPDATE_DEFAULT_RECIPIENT_PROPERTY Procedure
Update the default recipient property values. This procedure requires the user to have admin privileges. - UPDATE_DEFAULT_SHARE_PROPERTY Procedure
Update the default share property values. - UPDATE_RECIPIENT_PROPERTY Procedure
Update a property of an existing recipient. - UPDATE_SHARE_JOB_PROPERTY Procedure
Modify properties of a running share job. The procedure should return quickly, but it may take some time for the changes to take effect. - UPDATE_SHARE_PROPERTY Procedure
Update a property of an existing share. - UPDATE_SHARE_TABLE_PROPERTY Procedure
Update the property value of an existing share table. - VALIDATE_CREDENTIAL Function
Validate a credential name, converting it to canonical form first if required. - VALIDATE_SHARE_STORAGE Procedure
Check to see if the given storage is suitable for versioned shares. - WAIT_FOR_JOB Procedure
This procedure waits until the specified share job is complete.
Parent topic: DBMS_SHARE Package
ADD_TO_SHARE Procedure
Add a table or view to a share. The object becomes visible to any external user who has been granted access to the share.
Syntax
PROCEDURE ADD_TO_SHARE
(
share_name IN VARCHAR2,
table_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
share_table_name IN VARCHAR2 := NULL,
share_schema_name IN VARCHAR2 := NULL,
object_metadata IN SYS.JSON_OBJECT_T := NULL,
replace_existing IN BOOLEAN := FALSE,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of an existing share to which the object is granted. |
table_name |
The name of the entity to share (for example, a table or view name). |
owner |
The owner of the entity to share. The default is to current schema. |
share_table_name |
The externally
visible name of the table. By default, this is the uppercased
table_name .
|
share_schema_name |
The externally visible schema where the table will be placed. By default this is the uppercased table owner. The schema is created automatically if it does not already exist. |
object_metadata |
Optional metadata to associate with the shared entity. |
replace_existing |
If TRUE, and this
share_table_name already exists, the existing
table_name is dropped from the share and
replaced with this table_name .
If
FALSE, and this |
share_owner |
The owner of the share. |
auto_commit |
If TRUE, this procedure call commits changes that are not visible externally until the commit takes place. The default value is FALSE, which means that the user must COMMIT after running this call in order to make the change visible. |
Parent topic: Summary of Share Producer Subprograms
ASSERT_SHAREABLE_OBJECT Procedure
Return without error, if the object exists and can be shared.
Syntax
PROCEDURE ASSERT_SHAREABLE_OBJECT
(
object_name IN VARCHAR2,
object_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
object_name |
The name of the object. |
object_owner |
The owner of the object. Defaults to current schema. |
Parent topic: Summary of Share Producer Subprograms
ASSERT_SHARING_ID Procedure
Run basic validation checks against a sharing id and return one in canonical form. An exception is raised if the id is obviously invalid.
Syntax
PROCEDURE ASSERT_SHARING_ID
(
sharing_id IN OUT NOCOPY VARCHAR2,
out_sharing_id_type IN OUT NOCOPY VARCHAR2
);
Parameters
Parameter | Description |
---|---|
sharing_id |
The id to check. |
out_sharing_id_type |
The type of the
id, if valid. For example, TENANCY or
DATABASE .
|
Parent topic: Summary of Share Producer Subprograms
CAN_CREATE_SHARE Function
This function checks to see if the current schema can create share recipients. If shares can be created, a 1 is returned and 0 otherwise.
Syntax
FUNCTION CAN_CREATE_SHARE
RETURN NUMBER;
Example: Before and after enabling the admin schema
SQL> select dbms_share.can_create_share from dual;
CAN_CREATE_SHARE
----------------
0
SQL> exec dbms_share.enable_schema('admin')
PL/SQL procedure successfully completed.
SQL> select dbms_share.can_create_share from dual;
CAN_CREATE_SHARE
----------------
1
Parent topic: Summary of Share Producer Subprograms
CAN_CREATE_SHARE_RECIPIENT Function
This function checks to see if the current schema can create share recipients. If shares can be created a 1 is returned, and 0 otherwise.
Syntax
FUNCTION CAN_CREATE_SHARE_RECIPIENT
RETURN NUMBER;
Parent topic: Summary of Share Producer Subprograms
CLEAR_RECIPIENT_EVENTS Procedure
Clear events from the share recipient event log.
Syntax
PROCEDURE CLEAR_RECIPIENT_EVENTS
(
recipient_name IN VARCHAR2,
from_time IN TIMESTAMP WITH TIME ZONE := NULL,
to_time IN TIMESTAMP WITH TIME ZONE := NULL,
recipient_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of the share recipient. |
from_time |
Earliest time for events that should be cleared or NULL. |
to_time |
Latest time for events that should be cleared or NULL. |
recipient_owner |
The schema that owns the recipient. |
Parent topic: Summary of Share Producer Subprograms
CLEAR_SHARE_EVENTS Procedure
Clear events from the share event log.
Syntax
PROCEDURE CLEAR_SHARE_EVENTS
(
share_name IN VARCHAR2,
from_time IN TIMESTAMP WITH TIME ZONE := NULL,
to_time IN TIMESTAMP WITH TIME ZONE := NULL,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
from_time |
Earliest time for events that should be cleared or NULL. |
to_time |
Latest time for events that should be cleared or NULL. |
share_owner |
The schema that owns the share. |
Parent topic: Summary of Share Producer Subprograms
CREATE_BEARER_TOKEN_CREDENTIAL Procedure
Create a credential suitable for use with delta share providers.
CREATE_CREDENTIALS
call, but it takes
explicit values instead of a delta sharing profile. See CREATE_CREDENTIALS Procedure and Function for further information.
Syntax
PROCEDURE CREATE_BEARER_TOKEN_CREDENTIAL
(
credential_name IN VARCHAR2,
bearer_token IN VARCHAR2 := NULL,
token_endpoint IN VARCHAR2 := NULL,
client_id IN VARCHAR2 := NULL,
client_secret IN VARCHAR2 := NULL,
token_refresh_rate IN PLS_INTEGER := 3600
);
Parameters
Parameter | Description |
---|---|
credential_name |
The name of the new credential. |
bearer_token |
The bearer token, if known. |
token_endpoint |
The endpoint to call to get a new token. |
client_id |
The username to send to the token_endpoint. |
client_secret |
The password to send to the token_endpoint. |
token_refresh_rate |
An optional refresh time, in seconds. |
Example: Credential with a fixed bearer token
In its simplest form, this procedure is equivalent to calling
DBMS_CREDENTIAL
with a user name
of'BEARER_TOKEN'
and the bearer token itself as password.
SQL> exec dbms_share.create_bearer_token_credential('MY_FIXED_CREDENTIAL', 'FF42322D27D4C2DEE05392644664351E')
PL/SQL procedure successfully completed.
SQL> select username from user_credentials where credential_name = 'MY_FIXED_CREDENTIAL';
USERNAME
------------------------------------------------------------------------------------------------------------------------
BEARER_TOKEN
Example: Credential with a renewable bearer token
Create a credential that contains a short lived bearer token obtained from a token endpoint. The bearer token will be refreshed once every hour using a second credential, which is populated from the client id and secret.
SQL> BEGIN
2 dbms_share.create_bearer_token_credential(
3 credential_name=>'MY_RENEWABLE_CREDENTIAL',
4 token_endpoint=>'https://myserver/ords/share_provider/oauth/token',
5 client_id=>'VXGQ_44s6qJ-K4WHUNM2yQ..',
6 client_secret=>'y9ddppgwEmZl7adDHFQndw..');
7 END;
8 /
PL/SQL procedure successfully completed.
SQL> select credential_name, username from user_credentials where credential_name LIKE 'MY_RENEWABLE_CREDENTIAL%';
CREDENTIAL_NAME USERNAME
------------------------------------------ -------------------------------------
MY_RENEWABLE_CREDENTIAL BEARER_TOKEN
MY_RENEWABLE_CREDENTIAL$TOKEN_REFRESH_CRED VXGQ_44s6qJ-K4WHUNM2yQ..
Parent topic: Summary of Share Producer Subprograms
CREATE_CLOUD_STORAGE_LINK Procedure
Create a named cloud storage URI link. A cloud storage link is a named association between an OCI bucket URI, and a local credential name.
Syntax
PROCEDURE CREATE_CLOUD_STORAGE_LINK
(
storage_link_name IN VARCHAR2,
uri IN VARCHAR2,
owner IN VARCHAR2 := NULL,
metadata IN SYS.JSON_OBJECT_T := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
storage_link_name |
The name of the cloud storage link. The name of the link should follow standard Oracle naming conventions. |
uri |
The URI of the
storage bucket. The URI should be of the form
https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucket/o |
owner |
The owner of the storage link. Leave as NULL for the current user. |
metadata |
(Optional) A JSON metadata document containing additional information. |
auto_commit |
The default is TRUE. If TRUE, this transaction is committed. If FALSE, the user must commit the transaction. Changes are not visible until the commit takes place. |
Example
In this example, a cloud storage link named
MY_SHARE_STORAGE
is created on the given URL.
SQL> BEGIN
2 dbms_share.create_cloud_storage_link(
3 'MY_SHARE_STORAGE',
4 'https://objectstorage.../n/abcdef/b/my_bucket/o' );
5 END;
6 /
PL/SQL procedure successfully completed.
SQL> select storage_link_name from user_lineage_cloud_storage_links;
STORAGE_LINK_NAME
----------------------------------------------------------------------------------------
MY_SHARE_STORAGE
Parent topic: Summary of Share Producer Subprograms
CREATE_OR_REPLACE_CLOUD_STORAGE_LINK Procedure
Create or replace a named cloud storage URI. A cloud storage link is a named association between an OCI bucket URI, and a local credential name.
Syntax
PROCEDURE CREATE_OR_REPLACE_CLOUD_STORAGE_LINK
(
storage_link_name IN VARCHAR2,
uri IN VARCHAR2,
owner IN VARCHAR2 := NULL,
metadata IN SYS.JSON_OBJECT_T := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
storage_link_name |
The name of the cloud storage link. The name of the link should follow standard Oracle naming conventions. See Database Object Names and Qualifiers |
uri |
The URI of the
storage bucket. The URI should be of the form
https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucket/o |
owner |
The owner of the storage link. Defaults to the current schema. |
metadata |
An optional JSON metadata document containing additional information. |
auto_commit |
If TRUE, the changes automatically commit after creating the link. The default is TRUE. |
Parent topic: Summary of Share Producer Subprograms
CREATE_OR_REPLACE_SHARE_RECIPIENT Procedure
Create or replace a share recipient. You must provide at least an email address or sharing id.
Syntax
PROCEDURE CREATE_OR_REPLACE_SHARE_RECIPIENT
(
recipient_name IN VARCHAR2,
description IN VARCHAR2 := NULL,
recipient_owner IN VARCHAR2 := NULL,
email IN VARCHAR2 := NULL,
sharing_id IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of
the share recipient. Some names are not allowed (e.g.
MY_TENANCY ).
|
description |
A description of the recipient. |
recipient_owner |
The schema that owns the recipient. |
email |
An email that will be registered for the OAUTH user. |
sharing_id |
The sharing id of the recipient, from GET_SHARING_ID Function. |
Parent topic: Summary of Share Producer Subprograms
CREATE_SHARE Procedure
Create a named share object.
Syntax
PROCEDURE CREATE_SHARE
(
share_name IN VARCHAR2,
share_type IN VARCHAR2 := SHARE_TYPE_VERSIONED,
storage_link_name IN VARCHAR2 := NULL,
storage_link_owner IN VARCHAR2 := NULL,
description IN VARCHAR2 := NULL,
public_description IN VARCHAR2 := NULL,
configuration IN SYS.JSON_OBJECT_T := NULL,
force_create IN BOOLEAN := FALSE,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE,
log_level IN PLS_INTEGER := LOG_LEVEL_BASIC,
run_storage_tests IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. This name is uppercased since delta shares are case insensitive. The name follows standard Oracle conventions, so it must be 128 characters or fewer and must be double quoted if it is not a simple identifier. The only difference is that it will be uppercased even if it is double quoted. |
share_type |
The type of share. For information on constants used for this parameter, see descriptions for Share Types in DBMS_SHARE Constants. |
storage_link_name |
The name of the cloud storage link where the objects are created. The user must have read/write access to this storage and have the ability to create pre-authenticated requests on the storage. The parameter is required for versioned shares, and optional for current shares. |
storage_link_owner |
The owner of the cloud storage link where objects are created. |
description |
A local description for the share. |
public_description |
A public description for the share. |
configuration |
A configuration document that defines how objects are created. |
force_create |
Set
force_create to TRUE to redefine the share if
it exists.
|
share_owner |
The owner of the share. |
auto_commit |
If TRUE, this procedure call commits changes that are not visible externally until the commit takes place. The default value is FALSE, which means that the user must COMMIT after running this call in order to make the change visible. |
log_level |
Event logging level. This controls the amount of detail recorded in the ALL_SHARE_EVENTS View. For information on constants used for this parameter, see descriptions for Log Level in DBMS_SHARE Constants. |
run_storage_tests |
If this parameter
is TRUE then DBMS_SHARE runs tests to verify that
the specified share storage link has the correct privileges.
If this parameter is FALSE, then the procedure does not run any checks at creation time. This may lead to errors later, during publication or consumption of the share. Oracle recommends that you specify TRUE for this parameter. |
Parent topic: Summary of Share Producer Subprograms
CREATE_SHARE_RECIPIENT Procedure
Create a new share recipient.
Syntax
PROCEDURE CREATE_SHARE_RECIPIENT
(
recipient_name IN VARCHAR2,
description IN VARCHAR2 := NULL,
recipient_owner IN VARCHAR2 := NULL,
email IN VARCHAR2 := NULL,
sharing_id IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of
the share recipient. Some names are not allowed, for example:
MY_TENANCY .
|
description |
A description of the recipient. |
recipient_owner |
The schema that owns the recipient. |
email |
An email that will be registered for the OAUTH user. You must provide at least one of email or sharing id. |
sharing_id |
The sharing id of the recipient from GET_SHARING_ID Function. You must provide at least one of email or sharing id. |
Parent topic: Summary of Share Producer Subprograms
DROP_CLOUD_STORAGE_LINK Procedure
Drop a cloud storage link.
Syntax
PROCEDURE DROP_CLOUD_STORAGE_LINK
(
storage_link_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
storage_link_name |
The name of the cloud storage link to drop. |
owner |
The owner of the cloud storage link. Leave as NULL for the current user. |
auto_commit |
If TRUE, the code automatically commits after dropping the link. The default is TRUE. |
Parent topic: Summary of Share Producer Subprograms
DROP_RECIPIENT Procedure
Drop a recipient. All access to the recipient will be revoked.
Syntax
PROCEDURE DROP_RECIPIENT
(
recipient_name IN VARCHAR2,
owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The name of the share recipient. |
owner |
The schema that defines the recipient. |
Parent topic: Summary of Share Producer Subprograms
DROP_SHARE Procedure
Drop a share and all of its contents. Future access to the share by consumers will end.
Syntax
PROCEDURE DROP_SHARE
(
share_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
destroy_objects IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share to drop. |
share_owner |
The owner of the share to drop. |
destroy_objects |
If TRUE, delete all objects created on behalf of the share. The default is TRUE. |
Parent topic: Summary of Share Producer Subprograms
DROP_SHARE_LINK_VIEW Procedure
Drop a view that was created by the CREATE_SHARE_LINK_VIEW
procedure.
Syntax
PROCEDURE DROP_SHARE_LINK_VIEW
(
view_name IN VARCHAR2,
view_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
view_name |
The name of the new view. |
view_owner |
The view owner. The default is the current schema. |
Parent topic: Summary of Share Producer Subprograms
DROP_SHARE_VERSION Procedure
Drop a single share version. Note that you cannot drop the current version.
Syntax
PROCEDURE DROP_SHARE_VERSION
(
share_name IN VARCHAR2,
share_version IN NUMBER,
destroy_objects IN BOOLEAN := TRUE,
force_drop IN BOOLEAN := FALSE,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_version |
The version to drop. You can not drop the current version. |
destroy_objects |
Destroy any associated object in cloud storage, if applicable. |
force_drop |
Drop the share version even if there is an outstanding PAR file on the version. |
share_owner |
The owner of the share. |
Parent topic: Summary of Share Producer Subprograms
DROP_SHARE_VERSIONS Procedure
Drop a range of share versions. Note that you cannot drop the current version using this procedure.
Syntax
PROCEDURE DROP_SHARE_VERSIONS
(
share_name IN VARCHAR2,
from_share_version IN NUMBER,
to_share_version IN NUMBER,
destroy_objects IN BOOLEAN := TRUE,
force_drop IN BOOLEAN := FALSE,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
from_share_version |
The lowest version to drop. |
to_share_version |
The highest version to drop. |
destroy_objects |
Destroy any associated object in cloud storage, if applicable. |
force_drop |
Drop the share version even if there is an outstanding PAR file on the version. |
share_owner |
The owner of the share. |
Parent topic: Summary of Share Producer Subprograms
DROP_UNUSED_SHARE_VERSIONS Procedure
Drop any share version that is not currently in use.
Syntax
PROCEDURE DROP_UNUSED_SHARE_VERSIONS
(
share_name IN VARCHAR2,
destroy_objects IN BOOLEAN := TRUE,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
destroy_objects |
Destroy any associated object in cloud storage, if applicable. |
share_owner |
The owner of the share. |
Parent topic: Summary of Share Producer Subprograms
ENABLE_SCHEMA Procedure
Enable or disable a schema for sharing. This procedure must be run by the ADMIN user.
Syntax
Users can consume delta shares without being enabled with this procedure, but they cannot create or publish shares. Sharing is disabled by default for all schemas, including ADMIN.
PROCEDURE ENABLE_SCHEMA
(
schema_name IN VARCHAR2,
enabled IN BOOLEAN := TRUE,
privileges IN PLS_INTEGER := NULL
);
Parameters
Parameter | Description |
---|---|
schema_name |
The schema to enable or disable. |
enable |
TRUE to enable, FALSE to disable. |
privileges |
The privileges
argument has bitmap values. If you leave the argument as NULL, it
defaults to PRIV_CREATE_SHARE +
PRIV_CREATE_RECIPIENT +
PRIV_CONSUME_ORACLE_SHARE .
Bitmap values are as follows:
|
Parent topic: Summary of Share Producer Subprograms
GET_ACTIVATION_LINK Function
Generate the link that gets put into emails to the authorized recipient. This activation link leads to the download page, where the recipient clicks a button to get the delta profile.
Syntax
FUNCTION GET_ACTIVATION_LINK
(
recipient_name IN VARCHAR2,
recipient_owner IN VARCHAR2 := NULL,
expiration IN PLS_INTEGER := 259200,
invalidate_previous IN BOOLEAN := TRUE
)
RETURN VARCHAR2;
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of the recipient. |
recipient_owner |
The schema that owns the recipient. |
expiration |
Number of seconds before the activation link expires. |
invalidate_previous |
If TRUE, which is the default, a previously generated activation link is made invalid. If FALSE, a previously generated activation link remains valid. |
Example: Print activation link to the screen
SQL> exec dbms_share.create_share_recipient('new_recipient', email=>'anyone@example.com')
PL/SQL procedure successfully completed.
SQL> column PROFILE format A200
SQL> variable sprof varchar2(32767)
SQL> declare
2 profile sys.json_object_t;
3 begin
4 dbms_share.populate_share_profile('NEW_RECIPIENT', profile);
5 :sprof := profile.to_string;
6 end;
7 /
PL/SQL procedure successfully completed.
SQL> exec dbms_output.put_line(dbms_share.get_activation_link('NEW_RECIPIENT'))
http://.../ords/_adpshr/delta-sharing/download?key=43BA....YXJlX3Rlc3Q=
PL/SQL procedure successfully completed.
Parent topic: Summary of Share Producer Subprograms
GET_PUBLISHED_IDENTITY Function
Get data about the current user that was set by
SET_PUBLISHED_IDENTITY
.
Syntax
FUNCTION GET_PUBLISHED_IDENTITY
RETURN CLOB;
Example
SQL> declare
2 id_json json_object_t := json_object_t();
3 begin
4 id_json.put('name', 'Demo Publisher');
5 id_json.put('description', 'Documentation Share Provider');
6 id_json.put('contact', 'null@example.com');
7 dbms_share.set_published_identity(id_json);
8 end;
9 /
PL/SQL procedure successfully completed.
SQL> select json_query(dbms_share.get_published_identity, '$' pretty) "Published Identity"
2 from dual;
Published Identity-
-------------------------------------------------------------------------------
{
"name" : "Demo Publisher",
"description" : "Documentation Share Provider",
"contact" : "null@example.com"
}
Parent topic: Summary of Share Producer Subprograms
GET_RECIPIENT_PROPERTY Function
Return the value of a property for a recipient.
Syntax
FUNCTION GET_RECIPIENT_PROPERTY
(
recipient_name IN VARCHAR2,
recipient_property IN VARCHAR2,
recipient_owner IN VARCHAR2 := NULL
)RETURN VARCHAR2;
Parameters
Parameter | Description |
---|---|
recipient_name |
The name of the recipient. |
recipient_property |
The property to
get. These properties include:
For information on constants used for this parameter, see descriptions for Share Properties in DBMS_SHARE Constants. |
recipient_owner |
The owner of the recipient. Defaults to current user. |
Parent topic: Summary of Share Producer Subprograms
GET_SHARE_PROPERTY Function
Get the property value of an existing share.
Syntax
FUNCTION GET_SHARE_PROPERTY
(
share_name IN VARCHAR2,
share_property IN VARCHAR2,
share_owner IN VARCHAR2 := NULL
)
RETURN VARCHAR2
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_property |
The property value to get. For information on constants used for this parameter, see descriptions for Share Properties in DBMS_SHARE Constants. |
share_owner |
The owner of the share. Defaults to current user. |
Parent topic: Summary of Share Producer Subprograms
GET_SHARE_TABLE_PROPERTY Function
Get the property value of an existing share table.
Syntax
FUNCTION GET_SHARE_TABLE_PROPERTY
(
share_name IN VARCHAR2,
share_table_name IN VARCHAR2,
share_table_property IN VARCHAR2,
share_schema_name IN VARCHAR2 := NULL,
share_owner IN VARCHAR2 := NULL
)RETURN VARCHAR2;
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_table_name |
The name of the share table. |
share_table_property |
The share table property to update. For information on constants used for this parameter, see descriptions for Share Table Properties in DBMS_SHARE Constants. |
share_schema_name |
The name of the share schema. Defaults to uppercase of current user. |
share_owner |
The owner of the share. |
Parent topic: Summary of Share Producer Subprograms
GRANT_TO_RECIPIENT Procedure
Grant access on a share to a specific recipient. The share and recipient must both belong to the same schema.
Syntax
PROCEDURE GRANT_TO_RECIPIENT
(
share_name IN VARCHAR2,
recipient_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share to grant. |
recipient_name |
The name of the recipient. |
owner |
The owner of both the share and recipient. |
auto_commit |
The
auto_commit parameter is ignored. This
procedure will always commit.
|
Parent topic: Summary of Share Producer Subprograms
POPULATE_SHARE_PROFILE Procedure
Generate a delta profile for a recipient. You could print this to the screen
or upload it somewhere. For example, to an object bucket using
DBMS_CLOUD.EXPORT_DATA
.
Syntax
PROCEDURE POPULATE_SHARE_PROFILE
(
recipient_name IN VARCHAR2,
share_profile IN OUT NOCOPY SYS.JSON_OBJECT_T,
recipient_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of the recipient. |
share_profile |
The share profile, without bearer token. |
recipient_owner |
The schema that owns the recipient. |
Example: Print the profile to the screen.
SQL> EXEC DBMS_SHARE.CREATE_SHARE_RECIPIENT('new_recipient', email=>'anyone@example.com')
PL/SQL procedure successfully completed.
SQL> column PROFILE format A200
SQL> variable sprof varchar2(32767)
SQL> declare
2 profile sys.json_object_t;
3 begin
4 dbms_share.populate_share_profile('NEW_RECIPIENT', profile);
5 :sprof := profile.to_string;
6 end;
7 /
PL/SQL procedure successfully completed.
SQL> select json_query(:sprof, '$' pretty) "PROFILE" from dual;
PROFILE------------------------------------------------------------------------------------------------------------------------
{
"shareCredentialsVersion" : 1,
"endpoint" : "https://.../ords/share_test/_delta_sharing/",
"bearerToken" : "mc7puvhqCpU6xjTOjRdl_w",
"tokenEndpoint" : "https://.../ords/share_test/oauth/token",
"clientID" : "VXGQ_44s6qJ-K4WHUNM2yQ..",
"clientSecret" : "y9ddppgwEmZl7adDHFQndw.."
}
Parent topic: Summary of Share Producer Subprograms
PUBLISH_SHARE Procedure
Publish a share and return immediately.
USER_SHARE_JOBS
view. See USER_SHARE_JOBS View for further information.
Syntax
PROCEDURE PUBLISH_SHARE
(
share_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
drop_prior_versions IN BOOLEAN := FALSE,
share_job_dop IN NUMBER := NULL,
share_job_priority IN NUMBER := NULL,
job_class IN VARCHAR2 := 'DEFAULT_JOB_CLASS',
force_job_class IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share to publish. |
share_owner |
The share owner, which must be the current user or NULL. |
drop_prior_versions |
Set to TRUE if you want to drop all prior versions of the share. Note that versions are only dropped if there are no outstanding Pre-Authenticated Requests (PARs). |
share_job_dop |
Specify the
maximum number of dbms_scheduler jobs that will be
used to publish the share. Leave as NULL to use the system default
number.
|
share_job_priority |
Specify a relative priority of this share publication compared to others. If two shares are being published at the same time, then the one with the highest priority is processed first even if it was started later. |
job_class |
The scheduler job
class, from all_scheduler_job_classes , that are
used to publish the share.
|
force_job_class |
Use the
specifiedjob_class even if the admin has
defined a different default job class.
|
Parent topic: Summary of Share Producer Subprograms
PUBLISH_SHARE_WAIT Procedure
Publish a share and wait until the background job is complete. The publication continues even if the call is interrupted.
Syntax
PROCEDURE PUBLISH_SHARE_WAIT
(
share_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
drop_prior_versions IN BOOLEAN := FALSE,
share_job_dop IN NUMBER := NULL,
share_job_priority IN NUMBER := NULL,
job_class IN VARCHAR2 := 'DEFAULT_JOB_CLASS',
force_job_class IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share to publish. |
share_owner |
The share owner, which must be the current user or NULL. |
drop_prior_versions |
Set to TRUE if you want to drop all prior versions of the share. Note that versions are only dropped if there are no outstanding Pre-Authenticated Requests (PARs). |
share_job_dop |
Specify the
maximum number of dbms_scheduler jobs that will be
used to publish the share. Leave as NULL to use the system default
number.
|
share_job_priority |
Specify a relative priority of this share publication compared to others. If two shares are being published at the same time, then the one with the highest priority is processed first even if it was started later. |
job_class |
The scheduler job
class, from all_scheduler_job_classes , that are
used to publish the share.
|
force_job_class |
Use the
specifiedjob_class even if the admin has
defined a different default job class.
|
Parent topic: Summary of Share Producer Subprograms
PURGE_DETACHED_FILES Procedure
Delete or forget parquet files that have become detached from their shares.
Syntax
PROCEDURE PURGE_DETACHED_FILES
(
file_pattern IN VARCHAR2 := '%',
credential_name IN VARCHAR2 := NULL,
purge_mode IN PLS_INTEGER := PURGE_DROP,
owner_id IN NUMBER := SYS_CONTEXT('USERENV', 'CURRENT_USERID')
);
A version of PURGE_DETACHED_FILES
that returns the ID of the purge
job, if any.
PROCEDURE PURGE_DETACHED_FILES
(
purge_job_id IN OUT NOCOPY NUMBER,
file_pattern IN VARCHAR2 := '%',
credential_name IN VARCHAR2 := NULL,
purge_mode IN PLS_INTEGER := PURGE_DROP,
owner_id IN NUMBER := SYS_CONTEXT('USERENV', 'CURRENT_USERID')
);
Parameters
Parameter | Description |
---|---|
purge_job_id |
The purge job ID. |
file_pattern |
An optional LIKE pattern for the files that are to be purged. |
credential_name |
An optional credential to be used to delete the files. |
purge_mode |
Specifies how the
files are purged. Purge mode values include:
|
owner_id |
The owner ID whose files are to be purged. |
Parent topic: Summary of Share Producer Subprograms
REMOVE_FROM_SHARE Procedure
Remove a table or view from a share.
Syntax
PROCEDURE REMOVE_FROM_SHARE
(
share_name IN VARCHAR2,
share_table_name IN VARCHAR2,
share_schema_name IN VARCHAR2 := NULL,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of an existing share to which the object is revoked. |
share_table_name |
The name of the share table to revoke. This must match the externally visible name, so the input will be uppercased. |
share_schema_name |
The name of the share schema. Defaults to uppercase of current user. |
share_owner |
The owner of the share. |
auto_commit |
If TRUE, this procedure call commits changes that are not visible externally until the commit takes place. The default value is FALSE, which means that the user must COMMIT after running this call in order to make the change visible. |
Parent topic: Summary of Share Producer Subprograms
RENAME_RECIPIENT Procedure
Rename a recipient. This procedure only changes the local name of the recipient. The external definition of the recipient, for example the name of the OAUTH user or sharing id, is not changed.
Syntax
PROCEDURE RENAME_RECIPIENT
(
old_recipient_name IN VARCHAR2,
new_recipient_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
old_recipient_name |
The current name of the share recipient. |
new_recipient_name |
The new name of the share recipient. |
owner |
The schema that defines the recipient. |
auto_commit |
If TRUE, the changes are automatically committed. Changes are not visible externally until the commit takes place. The default is TRUE. |
Parent topic: Summary of Share Producer Subprograms
RENAME_SHARE Procedure
Rename a share. Care should be take with this procedure since the change effects any existing consumers whose access is based on the previous name. Consumers are not notified directly or updated.
Syntax
PROCEDURE RENAME_SHARE
(
old_share_name IN VARCHAR2,
new_share_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
old_share_name |
The current name of the share. |
new_share_name |
The new name of the share. |
share_owner |
The owner of the share. |
auto_commit |
If TRUE, the changes are automatically committed. Changes are not visible externally until the commit takes place. The default is TRUE. |
Parent topic: Summary of Share Producer Subprograms
RENAME_SHARE_LINK Procedure
Rename a registered share link.
Syntax
PROCEDURE RENAME_SHARE_LINK
(
old_name IN VARCHAR2,
new_name IN VARCHAR2,
link_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
old_name |
The current name of the share link. |
new_name |
The new name of the link. |
link_owner |
The owner of the share link. Defaults to current schema. |
Parent topic: Summary of Share Producer Subprograms
RENAME_SHARE_SCHEMA Procedure
Rename a share schema.
Syntax
PROCEDURE RENAME_SHARE_SCHEMA
(
share_name IN VARCHAR2,
old_schema_name IN VARCHAR2,
new_schema_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
old_schema_name |
The old name of the schema. |
new_schema_name |
The new name of the schema. |
share_owner |
The owner of the share. Defaults to the current schema. |
auto_commit |
If TRUE, the changes are automatically committed. Changes are not visible externally until the commit takes place. The default is FALSE. |
Parent topic: Summary of Share Producer Subprograms
RENAME_SHARE_TABLE Procedure
Rename a share table.
Syntax
PROCEDURE RENAME_SHARE_TABLE
(
share_name IN VARCHAR2,
share_schema_name IN VARCHAR2,
old_share_table_name IN VARCHAR2,
new_share_table_name IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_schema_name |
The name of the share schema. |
old_share_table_name |
The old name of the share table. |
new_share_table_name |
The new name of the share table. |
share_owner |
The owner of the share. |
auto_commit |
If TRUE, the changes are automatically committed. Changes are not visible externally until the commit takes place. The default is FALSE. |
Parent topic: Summary of Share Producer Subprograms
REVOKE_FROM_RECIPIENT Procedure
Revoke access on a share from a specific recipient.
Syntax
PROCEDURE REVOKE_FROM_RECIPIENT
(
share_name IN VARCHAR2,
recipient_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share to revoke. |
recipient_name |
The name of the recipient. |
owner |
The owner of the share and recipient. |
auto_commit |
If TRUE, the changes are automatically committed. Changes are not visible externally until the commit takes place. The default is FALSE. |
Parent topic: Summary of Share Producer Subprograms
SET_CURRENT_SHARE_VERSION Procedure
Change the current version of a share.
Syntax
PROCEDURE SET_CURRENT_SHARE_VERSION
(
share_name IN VARCHAR2,
share_version IN NUMBER,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_version |
The new version
or NULL. The version must exist and must be valid. If the
share_version is NULL, then no version will be
marked as CURRENT and the share will be "unpublished".
|
share_owner |
The owner of the share. Defaults to the current schema. |
Parent topic: Summary of Share Producer Subprograms
SET_PUBLISHED_IDENTITY Procedure
Set data about the current user that will be supplied to recipients of published ORACLE shares.
Syntax
PROCEDURE SET_PUBLISHED_IDENTITY
(
metadata IN SYS.JSON_OBJECT_T := NULL
);
Parameters
Parameter | Description |
---|---|
metadata |
If the provider
identity has already been set, then only the items that the caller
wants to update need to be included in the JSON. Supplying a NULL
value for an item causes that item to be removed from the stored
identity. However, "name", "description" and "contact" cannot be
removed in this way.
If the metadata argument is NULL, the existing provider identity is deleted. This can only happen if the current user has no published shares. If the provider
identity has not yet been set, the JSON must contain at
least:
Additional items may be included at the caller's discretion. |
Example: Include additional items in the JSON metadata
{
"name" : "A sample share provider",
"description" : "Test of share provider metadata",
"contact" : "provider1@example.com".
"schedule" : "New data provided on alternate rainy Fridays"
}
Example: Update "description" and remove "schedule"
{
"description" : "The Share Provider You Can Trust!(tm)",
"schedule" : null
}
Parent topic: Summary of Share Producer Subprograms
SET_RECIPIENT_LOG_LEVEL Procedure
Change the log level for an existing share recipient.
Syntax
PROCEDURE SET_RECIPIENT_LOG_LEVEL
(
recipient_name IN VARCHAR2,
log_level IN PLS_INTEGER,
recipient_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The local name of the share recipient. |
log_level |
Event logging level. For information on constants used for this parameter, see descriptions for Log Level in DBMS_SHARE Constants. |
recipient_owner |
The schema that owns the recipient. |
Parent topic: Summary of Share Producer Subprograms
SET_SHARE_LOG_LEVEL Procedure
Change the log level for an existing share.
Syntax
PROCEDURE SET_SHARE_LOG_LEVEL
(
share_name IN VARCHAR2,
log_level IN PLS_INTEGER,
share_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
log_level |
Event logging level. For information on constants used for this parameter, see descriptions for Log Level in DBMS_SHARE Constants. |
share_owner |
The owner of the share. |
Parent topic: Summary of Share Producer Subprograms
SET_STORAGE_CREDENTIAL Procedure
Set the credential name used by the current user when it attempts to access the given storage.
Syntax
PROCEDURE SET_STORAGE_CREDENTIAL
(
storage_link_name IN VARCHAR2,
credential_name IN VARCHAR2,
owner IN VARCHAR2 := NULL,
check_if_exists IN BOOLEAN := TRUE,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
storage_link_name |
The name of a cloud storage link previously created using CREATE_CLOUD_STORAGE_LINK Procedure. |
credential_name |
The name of a
local credential that gives access to the storage.
The credentials used for share storage must be able to read, write, delete, and manage pre-authenticated requests. See Using Pre-Authenticated Requests |
owner |
The owner of the cloud storage link. Leave as NULL for the current user. |
check_if_exists |
If
check_if_exists is TRUE, then the function will
also confirm that the credential exists for the current
user.
|
auto_commit |
The default is TRUE. If TRUE, this transaction is committed. If FALSE, the user must commit the transaction. Changes are not visible until the commit takes place. |
Parent topic: Summary of Share Producer Subprograms
STOP_JOB Procedure
Attempt to stop a running share job. The procedure should return quickly, but it may take some time for the associated job to stop.
Syntax
PROCEDURE STOP_JOB
(
share_job_id IN NUMBER,
share_job_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_job_id |
The ID of the share job. |
share_job_owner |
The owner of the job. Defaults to the current schema. |
Parent topic: Summary of Share Producer Subprograms
UNPUBLISH_SHARE Procedure
Unpublish a share.
Syntax
PROCEDURE UNPUBLISH_SHARE
(
share_name IN VARCHAR2,
out_share_job_id IN OUT NOCOPY NUMBER,
share_owner IN VARCHAR2 := NULL,
drop_all_versions IN BOOLEAN := FALSE,
restart_versions IN BOOLEAN := FALSE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
out_share_job_id |
The ID of any share job that needs to be run to process this command. |
share_owner |
The owner of the share. Defaults to the current schema. |
drop_all_versions |
If set to TRUE,
all existing versions along with all associated storage is
dropped.
If |
restart_versions |
Restart version
numbering. If FALSE, then the next published version number will be
the same as it would have been if no versions had been dropped.
If
TRUE, then the next published version will be set to one more
than the highest existing version. When used in conjunction with
|
Parent topic: Summary of Share Producer Subprograms
UPDATE_DEFAULT_RECIPIENT_PROPERTY Procedure
Update the default recipient property values. This procedure requires the user to have admin privileges.
Syntax
PROCEDURE UPDATE_DEFAULT_RECIPIENT_PROPERTY
(
recipient_property IN VARCHAR2,
new_value_vc IN VARCHAR2
);
Parameters
Parameter | Description |
---|---|
recipient_property |
The property to update. For information on constants used for this parameter, see descriptions for Share Recipient Properties in DBMS_SHARE Constants. |
new_value_vc |
The new property value. |
Parent topic: Summary of Share Producer Subprograms
UPDATE_DEFAULT_SHARE_PROPERTY Procedure
Update the default share property values.
Syntax
PROCEDURE UPDATE_DEFAULT_SHARE_PROPERTY
(
share_property IN VARCHAR2,
new_value IN VARCHAR2
);
Parameters
Parameter | Description |
---|---|
share_property |
The property to
update. For information on constants used for this parameter, see
descriptions for Share Properties in DBMS_SHARE Constants.
These properties can be read using the ALL_SHARE_DEFAULT_SETTINGS View. |
new_value |
The new property value. |
Parent topic: Summary of Share Producer Subprograms
UPDATE_RECIPIENT_PROPERTY Procedure
Update a property of an existing recipient.
Syntax
PROCEDURE UPDATE_RECIPIENT_PROPERTY
(
recipient_name IN VARCHAR2,
recipient_property IN VARCHAR2,
new_value IN VARCHAR2,
recipient_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
recipient_name |
The name of the recipient. |
recipient_property |
The property to
update. These properties include:
|
new_value |
The new property value. |
recipient_owner |
The owner of the recipient. Defaults to the current schema. |
Parent topic: Summary of Share Producer Subprograms
UPDATE_SHARE_JOB_PROPERTY Procedure
Modify properties of a running share job. The procedure should return quickly, but it may take some time for the changes to take effect.
Syntax
PROCEDURE UPDATE_SHARE_JOB_PROPERTY
(
share_job_id IN NUMBER,
share_property IN VARCHAR2,
new_value IN VARCHAR2,
share_job_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
share_job_id |
The ID of the share job. |
share_property |
The property to update. For information on constants used for this parameter, see descriptions for Share Job Properties in DBMS_SHARE Constants. |
new_value |
The new property value. |
share_job_owner |
The owner of the job. Defaults to the current schema. |
Parent topic: Summary of Share Producer Subprograms
UPDATE_SHARE_PROPERTY Procedure
Update a property of an existing share.
Syntax
PROCEDURE UPDATE_SHARE_PROPERTY
(
share_name IN VARCHAR2,
share_property IN VARCHAR2,
new_value IN VARCHAR2,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_property |
The property to update. For information on constants used for this parameter, see descriptions for Share Properties in DBMS_SHARE Constants. |
new_value |
The new property value. |
share_owner |
The owner of the share. Defaults to the current schema. |
Auto_commit |
If TRUE (the default), the changes are automatically committed. If FALSE, the user must commit the changes. Changes are visible externally after the commit takes place. |
Parent topic: Summary of Share Producer Subprograms
UPDATE_SHARE_TABLE_PROPERTY Procedure
Update the property value of an existing share table.
Syntax
PROCEDURE UPDATE_SHARE_TABLE_PROPERTY
(
share_name IN VARCHAR2,
share_table_name IN VARCHAR2,
share_table_property IN VARCHAR2,
new_value IN VARCHAR2,
share_schema_name IN VARCHAR2 := NULL,
share_owner IN VARCHAR2 := NULL,
auto_commit IN BOOLEAN := TRUE
);
Parameters
Parameter | Description |
---|---|
share_name |
The name of the share. |
share_table_name |
The name of the share table. |
share_table_property |
The property to
update. These properties include:
|
new_value |
The new property value. |
share_schema_name |
The name of the share schema (defaults to uppercase of current user). |
share_owner |
The owner of the share. Defaults to the current schema. |
Auto_commit |
If TRUE (the default), the changes are automatically committed. If FALSE, the user must commit the changes. Changes are visible externally after the commit takes place. |
Parent topic: Summary of Share Producer Subprograms
VALIDATE_CREDENTIAL Function
Validate a credential name, converting it to canonical form first if required.
The procedure raises an exception if the name is not a valid Oracle
identifier. The credential_name
is returned without double quotes,
as it would appear in the CREDENTIAL_NAME
column of the
USER_CREDENTIALS
view.
Syntax
FUNCTION VALIDATE_CREDENTIAL
(
credential_name IN VARCHAR2,
check_if_exists IN BOOLEAN := TRUE
)
RETURN VARCHAR2;
Parameters
Parameter | Description |
---|---|
credential_name |
The name of the credential to validate in standard database form, with double quotes if the name is not a simple identifier. |
check_if_exists |
If TRUE, then the function also confirms that the credential exists for the current user. |
Parent topic: Summary of Share Producer Subprograms
VALIDATE_SHARE_STORAGE Procedure
Check to see if the given storage is suitable for versioned shares.
Syntax
The procedure syntax including the validation_results
output
parameter.
PROCEDURE VALIDATE_SHARE_STORAGE
(
storage_link_name IN VARCHAR2,
validation_results IN OUT NOCOPY VARCHAR2,
run_storage_tests IN BOOLEAN := TRUE,
storage_link_owner IN VARCHAR2 := NULL
);
The procedure syntax not including the validation_results
output
parameter.
PROCEDURE VALIDATE_SHARE_STORAGE
(
storage_link_name IN VARCHAR2,
run_storage_tests IN BOOLEAN := TRUE,
storage_link_owner IN VARCHAR2 := NULL
);
Parameters
Parameter | Description |
---|---|
storage_link_name |
The cloud storage link name. |
validation_results |
(Optional input
and output) Validation result details returned in JSON form.
The
|
run_storage_tests |
Run tests to validate the storage. If TRUE (the default), the procedure tests READ, WRITE, DELETE, and PREAUTHENTICATED REQUESTS. |
storage_link_owner |
The cloud storage link owner. |
Example: Validation results
{
"READ":"PASSSED",
"WRITE":"PASSSED",
"CREATE_PAR":"PASSSED",
"DELETE_PAR":"PASSSED",
"DELETE":"PASSSED"
}
Parent topic: Summary of Share Producer Subprograms
WAIT_FOR_JOB Procedure
This procedure waits until the specified share job is complete.
Syntax
PROCEDURE WAIT_FOR_JOB
(
share_job_id IN NUMBER,
completed IN OUT NOCOPY BOOLEAN,
maximum_wait IN NUMBER := NULL
);
Parameters
Parameter | Description |
---|---|
share_job_id |
The ID of the share job. |
completed |
Job completion indicator. |
maximum_wait |
The maximum wait period, in seconds. A NULL value implies no limit. |
Parent topic: Summary of Share Producer Subprograms