# Procedimentos armazenados externos do Amazon RDS para Db2 É possível criar rotinas externas e registrá-las em bancos de dados do Amazon RDS para Db2 como procedimentos armazenados externos. No momento, o RDS para Db2 permite somente rotinas baseadas em Java para procedimentos armazenados externos. ## Procedimentos armazenados externos baseados em Java Procedimentos armazenados externos baseados em Java são rotinas externas do Java que você registra no banco de dados do RDS para Db2 como procedimentos armazenados externos. **Topics** + [Limitações para procedimentos armazenados externos baseados em Java](#db2-external-stored-procedures-java-limitations) + [Configurar procedimentos armazenados externos baseados em Java](#db2-external-stored-procedures-java-configuring) ### Limitações para procedimentos armazenados externos baseados em Java Antes de desenvolver a rotina externa, considere as seguintes limitações e restrições. Para criar a rotina externa, use o Java Development Kit (JDK) fornecido pelo Db2. Consulte mais informações em [Java software support for Db2 database products](https://www.ibm.com/docs/en/db2/11.5?topic=servers-java-software-support-db2-database-products). O programa Java pode criar arquivos somente no diretório `/tmp`, e o Amazon RDS não permite habilitar permissões executáveis ou de definição de ID de usuário (SUID) nesses arquivos. O programa Java também não pode usar chamadas de sistema de soquete nem as seguintes chamadas de sistema: + \$1sysctl + acct + afs\$1syscall + bpf + capset + chown + chroot + create\$1module + delete\$1module + fanotify\$1init + fanotify\$1mark + finit\$1module + fsconfig + fsopen + fspick + get\$1kernel\$1syms + getpmsg + init\$1module + mount + move\$1mount + nfsservctl + open\$1by\$1handle\$1at + open\$1tree + pivot\$1root + putpmsg + query\$1module + quotactl + reboot + security + setdomainname + setfsuid + sethostname + sysfs + tuxcall + umount2 + uselib + ustat + vhangup + vserver Consulte as restrições adicionais sobre rotinas externas para o Db2 em [Restrictions on external routines](https://www.ibm.com/docs/en/db2/11.5?topic=routines-restrictions-external) na documentação do IBM Db2. ### Configurar procedimentos armazenados externos baseados em Java Para configurar um procedimento armazenado externo, crie um arquivo .jar com a rotina externa, instale-o no banco de dados do RDS para Db2 e, depois, registre-o como um procedimento armazenado externo. **Topics** + [Etapa 1: habilitar procedimentos armazenados externos](#db2-external-stored-procedures-java-enable) + [Etapa 2: instalar o arquivo .jar com a rotina externa](#db2-external-stored-procedures-java-install-jar) + [Etapa 3: registrar o procedimento armazenado externo](#db2-external-stored-procedures-java-register) + [Etapa 4: validar o procedimento armazenado externo](#db2-external-stored-procedures-java-validate) #### Etapa 1: habilitar procedimentos armazenados externos Para habilitar procedimentos armazenados externos, em um grupo de parâmetros personalizado associado à instância de banco de dados, defina o parâmetro `db2_alternate_authz_behaviour` como um dos seguintes valores: + `EXTERNAL_ROUTINE_DBADM`: concede implicitamente a permissão `CREATE_EXTERNAL_ROUTINE` a qualquer usuário, grupo ou perfil com a autoridade `DBADM`. + `EXTERNAL_ROUTINE_DBAUTH`: permite que um usuário com a autoridade `DBADM` conceda a permissão `CREATE_EXTERNAL_ROUTINE` a qualquer usuário, grupo ou perfil. Nesse caso, nenhum usuário, grupo ou perfil recebe essa permissão implicitamente, nem mesmo um usuário com a autoridade `DBADM`. Consulte mais informações sobre essa configuração em [GRANT (database authorities) statement](https://www.ibm.com/docs/en/db2/11.5?topic=statements-grant-database-authorities) na documentação do IBM Db2. É possível criar e modificar um grupo de parâmetros personalizado usando o Console de gerenciamento da AWS, a AWS CLI ou a API do Amazon RDS. ##### Console **Para configurar o parâmetro db2\$1alternate\$1authz\$1behaviour em um grupo de parâmetros personalizado** 1. Se você quiser usar um grupo de parâmetros de banco de dados personalizado diferente do que o que a instância de banco de dados está usando, crie outro grupo de parâmetros de banco de dados. Se você estiver usando o modelo traga a sua própria licença (BYOL), garanta que o novo grupo de parâmetros personalizado inclua os IDs da IBM. Consulte informações sobre esses IDs em [IDs da IBM para traga a sua própria licença (BYOL) para o Db2](db2-licensing.md#db2-prereqs-ibm-info). Para obter mais informações sobre como criar um parameter group de banco de dados, consulte [Criar um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Creating.md). 1. Defina o valor do parâmetro `db2_alternate_authz_behaviour` em seu grupo de parâmetros personalizado. Para ter mais informações sobre como modificar um grupo de parâmetros, consulte [Modificar parâmetros em um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Modifying.md). ##### AWS CLI **Para configurar o parâmetro db2\$1alternate\$1authz\$1behaviour em um grupo de parâmetros personalizado** 1. Se você quiser usar um grupo de parâmetros de banco de dados personalizado diferente do que o que a instância de banco de dados está usando, crie um grupo de parâmetros de personalizado executando o comando [https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-parameter-group.html](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-parameter-group.html). Se você estiver usando o modelo traga a sua própria licença (BYOL), garanta que o novo grupo de parâmetros personalizado inclua os IDs da IBM. Consulte informações sobre esses IDs em [IDs da IBM para traga a sua própria licença (BYOL) para o Db2](db2-licensing.md#db2-prereqs-ibm-info). Inclua as seguintes opções necessárias: + `--db-parameter-group-name`: um nome para o grupo de parâmetros que você está criando. + `--db-parameter-group-family`: a edição do mecanismo do Db2 e a versão principal. Os valores válidos são `db2-se-11.5` e `db2-ae-11.5`. + `--description`: a descrição desse grupo de parâmetros. Para obter mais informações sobre como criar um parameter group de banco de dados, consulte [Criar um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Creating.md). O exemplo a seguir mostra como criar um grupo de parâmetros personalizado chamado `MY_EXT_SP_PARAM_GROUP` para a família do grupos de parâmetros `db2-se-11.5`. Para Linux, macOS ou Unix: ``` aws rds create-db-parameter-group \ --region us-east-1 \ --db-parameter-group-name MY_EXT_SP_PARAM_GROUP \ --db-parameter-group-family db2-se-11.5 \ --description "test db2 external routines" ``` Para Windows: ``` aws rds create-db-parameter-group ^ --region us-east-1 ^ --db-parameter-group-name MY_EXT_SP_PARAM_GROUP ^ --db-parameter-group-family db2-se-11.5 ^ --description "test db2 external routines" ``` 1. Modifique o parâmetro `db2_alternate_authz_behaviour` em seu grupo de parâmetros personalizado executando o comando [https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-parameter-group.html). Inclua as seguintes opções necessárias: + `--db-parameter-group-name`: o nome do grupo de parâmetros criado. + `--parameters`: uma matriz de nomes de parâmetros, valores e os métodos de aplicação da atualização de parâmetros. Para ter mais informações sobre como modificar um grupo de parâmetros, consulte [Modificar parâmetros em um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Modifying.md). O exemplo a seguir mostra como modificar o grupo de parâmetros `MY_EXT_SP_PARAM_GROUP` definindo o valor de `db2_alternate_authz_behaviour` como `EXTERNAL_ROUTINE_DBADM`. Para Linux, macOS ou Unix: ``` aws rds modify-db-parameter-group \ --db-parameter-group-name MY_EXT_SP_PARAM_GROUP \ --parameters "ParameterName='db2_alternate_authz_behaviour',ParameterValue='EXTERNAL_ROUTINE_DBADM',ApplyMethod=immediate" ``` Para Windows: ``` aws rds modify-db-parameter-group ^ --db-parameter-group-name MY_EXT_SP_PARAM_GROUP ^ --parameters "ParameterName='db2_alternate_authz_behaviour',ParameterValue='EXTERNAL_ROUTINE_DBADM',ApplyMethod=immediate" ``` ##### API do RDS **Para configurar o parâmetro db2\$1alternate\$1authz\$1behaviour em um grupo de parâmetros personalizado** 1. Se você quiser usar um grupo de parâmetros de banco de dados personalizado diferente do que o que a instância de banco de dados está usando, crie outro grupo de parâmetros de banco de dados usando a operação de API [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBParameterGroup.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBParameterGroup.html) do Amazon RDS. Se você estiver usando o modelo traga a sua própria licença (BYOL), garanta que o novo grupo de parâmetros personalizado inclua os IDs da IBM Db2. Consulte informações sobre esses IDs em [IDs da IBM para traga a sua própria licença (BYOL) para o Db2](db2-licensing.md#db2-prereqs-ibm-info). Inclua os seguintes parâmetros necessários: + `DBParameterGroupName` + `DBParameterGroupFamily` + `Description` Para obter mais informações sobre como criar um parameter group de banco de dados, consulte [Criar um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Creating.md). 1. Modifique o parâmetro `db2_alternate_authz_behaviour` no grupo de parâmetros personalizado que você criou usando a operação de API [https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBParameterGroup.html](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBParameterGroup.html) do RDS. Inclua os seguintes parâmetros necessários: + `DBParameterGroupName` + `Parameters` Para ter mais informações sobre como modificar um grupo de parâmetros, consulte [Modificar parâmetros em um grupo de parâmetros de banco de dados no Amazon RDS](USER_WorkingWithParamGroups.Modifying.md). #### Etapa 2: instalar o arquivo .jar com a rotina externa Depois de criar a rotina do Java, crie o arquivo .jar e execute `db2 "call sqlj.install_jar('file:file_path',jar_ID)"` para instalá-lo no banco de dados do RDS para Db2. O exemplo a seguir mostra como criar uma rotina do Java e instalá-la em um banco de dados do RDS para Db2. O exemplo inclui um exemplo de código para uma rotina simples que pode ser usada para testar o processo. Esse exemplo faz as seguintes suposições: + O código Java é compilado em um servidor em que o Db2 está instalado. Essa é uma prática recomendada porque não compilar com o JDK fornecido pela IBM pode resultar em erros inexplicáveis. + O servidor tem o banco de dados do RDS para Db2 catalogado localmente. Se você quiser experimentar o processo com o código de exemplo a seguir, copie-o e salve-o em um arquivo chamado `MYJAVASP.java`. ``` import java.sql.*; public class MYJAVASP { public static void my_JAVASP (String inparam) throws SQLException, Exception { try { // Obtain the calling context's connection details. Connection myConn = DriverManager.getConnection("jdbc:default:connection"); String myQuery = "INSERT INTO TEST.TEST_TABLE VALUES (?, CURRENT DATE)"; PreparedStatement myStmt = myConn.prepareStatement(myQuery); myStmt.setString(1, inparam); myStmt.executeUpdate(); } catch (SQLException sql_ex) { throw sql_ex; } catch (Exception ex) { throw ex; } } ``` O comando a seguir compila a rotina do Java. ``` ~/sqllib/java/jdk64/bin/javac MYJAVASP.java ``` O comando a seguir cria o arquivo .jar. ``` ~/sqllib/java/jdk64/bin/jar cvf MYJAVASP.jar MYJAVASP.class ``` Os comandos a seguir se conectam ao banco de dados chamado `MY_DB2_DATABASE` e instalam o arquivo .jar. ``` db2 "connect to MY_DB2_DATABASE user master_username using master_password" db2 "call sqlj.install_jar('file:/tmp/MYJAVASP.jar','MYJAVASP')" db2 "call sqlj.refresh_classes()" ``` #### Etapa 3: registrar o procedimento armazenado externo Depois de instalar o arquivo .jar no banco de dados do RDS para Db2, registre-o como um procedimento armazenado executando o comando `db2 CREATE PROCEDURE` ou `db2 REPLACE PROCEDURE`. O exemplo a seguir mostra como se conectar ao banco de dados e registrar a rotina do Java criada na etapa anterior como um procedimento armazenado. ``` db2 "connect to MY_DB2_DATABASE user master_username using master_password" create procedure TESTSP.MYJAVASP (in input char(6)) specific myjavasp dynamic result sets 0 deterministic language java parameter style java no dbinfo fenced threadsafe modifies sql data program type sub external name 'MYJAVASP!my_JAVASP'; ``` #### Etapa 4: validar o procedimento armazenado externo Use as etapas a seguir para testar o exemplo de procedimento armazenado externo que foi registrado na etapa anterior. **Como validar o procedimento armazenado externo** 1. Crie uma tabela como `TEST.TEST_TABLE` no exemplo a seguir. ``` db2 "create table TEST.TEST_TABLE(C1 char(6), C2 date)" ``` 1. Chame o novo procedimento armazenado externo. A chamada retorna um status de `0`. ``` db2 "call TESTSP.MYJAVASP('test')" Return Status = 0 ``` 1. Consulte a tabela que você criou na etapa 1 para verificar os resultados da chamada do procedimento armazenado. ``` db2 "SELECT * from TEST.TEST_TABLE" ``` A consulta produz um resultado semelhante ao seguinte exemplo: ``` C1 C2 ------ ---------- test 02/05/2024 ```