Como usar sequências de escape do SQL
O Microsoft JDBC Driver para SQL Server dá suporte ao uso de sequências de escape do SQL, conforme definido pela API do JDBC. As sequências de escape são usadas em uma instrução SQL para informar ao driver que a parte de escape da cadeia de caracteres SQL deve ser tratada de forma diferente. Quando o driver JDBC processa a parte de escape de uma cadeia de caracteres SQL, ele converte essa parte da cadeia de caracteres em código SQL que o SQL Server entende.
Há cinco tipos de sequências de escape requeridas pela API JDBC e todos têm o suporte do driver JDBC:
- Literais do curinga LIKE
- Manipulação de função
- Literais de data e hora
- Chamadas de procedimento armazenado
- Junções externas
- Sintaxe de escape de limite
A sintaxe da sequência de escape usada pelo driver JDBC é a seguinte:
{keyword ...parameters...}
Observação
O processamento de escape do SQL sempre está ativado para o driver JDBC.
As seções a seguir descrevem os cinco tipos de sequências de escape e como elas têm o suporte do driver JDBC.
Literais do curinga LIKE
O driver JDBC é compatível com a sintaxe {escape 'escape character'} para uso de curingas da cláusula LIKE como literais. Por exemplo, o código a seguir retornará valores para col3, onde o valor de col2 começa literalmente com um sublinhado (e não seu uso de curinga).
ResultSet rst = stmt.executeQuery("SELECT col3 FROM test1 WHERE col2
LIKE '\\_%' {escape '\\'}");
Observação
A sequência de escape deve estar no fim da instrução SQL. Para várias instruções SQL em uma cadeia de caracteres de comando, a sequência de escape precisa estar no fim de cada instrução SQL pertinente.
Manipulação de função
O driver JDBC dá suporte às sequências de escape de função em instruções SQL com a seguinte sintaxe:
{fn functionName}
em que functionName é uma função compatível com o driver JDBC. Por exemplo:
SELECT {fn UCASE(Name)} FROM Employee
A tabela a seguir lista as várias funções que têm o suporte do driver JDBC ao usar uma sequência de escape de função:
| Funções de Cadeia de Caracteres | Funções numéricas | Funções de data e hora | Funções de sistema |
|---|---|---|---|
| ASCII CHAR CONCAT DIFFERENCE INSERT LCASE LEFT LENGTH LOCATE LTRIM REPEAT REPLACE RIGHT RTRIM SOUNDEX SPACE SUBSTRING UCASE |
ABS ACOS ASIN ATAN ATAN2 CEILING COS COT DEGREES EXP FLOOR LOG LOG10 MOD PI POWER RADIANS RAND ROUND SIGN SIN SQRT TAN TRUNCATE |
CURDATE CURTIME DAYNAME DAYOFMONTH DAYOFWEEK DAYOFYEAR EXTRACT HOUR MINUTE MONTH MONTHNAME NOW QUARTER SECOND TIMESTAMPADD TIMESTAMPDIFF WEEK YEAR |
DATABASE IFNULL USER |
Observação
Se você tentar usar uma função que não tenha o suporte do banco de dados, ocorrerá um erro.
Literais de data e hora
A sintaxe de escape para data, hora e literais de carimbo de data/hora é a seguinte:
{literal-type 'value'}
em que literal-type é um dos seguintes:
| Tipo de literal | Descrição | Formato do valor |
|---|---|---|
| d | Data | aaaa-mm-dd |
| t | Hora | hh:mm:ss [1] |
| ts | TimeStamp | aaaa-mm-dd hh:mm:ss[.f...] |
Por exemplo:
UPDATE Orders SET OpenDate={d '2005-01-31'}
WHERE OrderID=1025
Chamadas de procedimento armazenado
O driver JDBC é compatível com as sintaxes de escape {? = call proc_name(?,...)} e {call proc_name(?,...)} para chamadas de procedimento armazenado, dependendo da necessidade de processar um parâmetro de retorno.
Um procedimento é um objeto executável armazenado no banco de dados. Em geral, é uma ou mais instruções SQL que foram pré-compiladas. A sintaxe da sequência de escape para chamar um procedimento armazenado é a seguinte:
{[?=]call procedure-name[([parameter][,[parameter]]...)]}
em que procedure-name especifica o nome de um procedimento armazenado e parameter especifica um parâmetro de procedimento armazenado.
Para obter mais informações sobre o uso da sequência de escape call com procedimentos armazenados, confira Como usar instruções com procedimentos armazenados.
Junções externas
O driver JDBC dá suporte à sintaxe de junção externa esquerda, direita e completa do SQL92. A sequência de escape de junções externas é a seguinte:
{oj outer-join}
onde outer-join é:
table-reference {LEFT | RIGHT | FULL} OUTER JOIN
{table-reference | outer-join} ON search-condition
em que table-reference é um nome de tabela e search-condition é a condição de junção que você deseja usar para as tabelas.
Por exemplo:
SELECT Customers.CustID, Customers.Name, Orders.OrderID, Orders.Status
FROM {oj Customers LEFT OUTER JOIN
Orders ON Customers.CustID=Orders.CustID}
WHERE Orders.Status='OPEN'
As seguintes sequências de escape de junção externa têm o suporte do driver JDBC:
- Junções externas esquerdas
- Junções externas direitas
- Junções externas completas
- Junções externas aninhadas
Sintaxe de escape de limite
Observação
A sintaxe de escape LIMIT só tem suporte pelo Microsoft JDBC Driver 4.2 (ou superior) for SQL Server ao usar JDBC 4.1 ou superior.
A sintaxe de escape LIMIT é da seguinte maneira:
LIMIT <rows> [OFFSET <row offset>]
A sintaxe de escape tem duas partes: <rows> é obrigatória e especifica o número de linhas a serem retornadas. OFFSET e <deslocamento da linha> são opcionais e especificam o número de linhas a serem ignoradas antes de começar a retornar linhas. O driver JDBC dá suporte apenas à parte obrigatória, transformando a consulta para usar TOP em vez de LIMIT. O SQL Server não d suporte à cláusula LIMIT. O driver JDBC não dá suporte opcional <deslocamento da linha> e o driver gerará uma exceção se for usado.