Esta seção descreve as facilidades que as bibliotecas de interface cliente do PostgreSQL fornecem para acessar objetos grandes. Toda manipulação de objeto grande que utiliza estas funções deve acontecer dentro de um bloco de transação SQL (Este requisito é exigido desde o PostgreSQL 6.5, embora tenha sido um requisito implícito nas versões anteriores, resultando em um mal comportamento quando ignorado). A interface de objeto grande do PostgreSQL é modelada segundo a interface do sistema de arquivos do Unix, com funções open, read, write, lseek, etc. análogas.
Os aplicativos cliente que utilizam a interface de objeto grande da libpq devem incluir o arquivo de cabeçalho libpq/libpq-fs.h, e fazer a ligação com a biblioteca libpq.
A função
Oid lo_creat(PGconn *conn, int modo);
cria um objeto grande novo. O argumento modo é uma máscara de bits que descreve vários atributos diferentes do novo objeto. As constantes simbólicas usadas aqui são definidas no arquivo de cabeçalho libpq/libpq-fs.h. O tipo de acesso (leitura, escrita ou ambos) é controlado pelo OU lógico dos bits de INV_READ e INV_WRITE. Os dezesseis bits de mais baixa ordem da máscara têm sido utilizados em Berkeley, historicamente, para designar o número do gerenciador de armazenamento no qual o objeto grande deve residir. Agora estes bits devem ser sempre zero. O valor retornado é o OID atribuído ao novo objeto grande (o tipo de acesso também não faz mais nada, mas deve ser definido pelo menos um dos sinalizadores para evitar erro). O valor retornado é o OID atribuído ao novo objeto grande, ou InvalidOid (zero) se não for bem-sucedido.
Exemplo:
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
Para importar um arquivo do sistema operacional como um objeto grande é chamada a função:
Oid lo_import(PGconn *conn, const char *nome_do_arquivo);
O argumento nome_do_arquivo especifica o nome do arquivo do sistema operacional a ser importado para o novo objeto grande. O valor retornado é o OID atribuído ao novo objeto grande, ou InvalidOid (zero) se não for bem-sucedido. Deve ser observado que o arquivo é lido pela biblioteca de interface cliente, e não pelo servidor; portanto, o arquivo deve residir no sistema de arquivos do cliente e poder ser lido pelo aplicativo cliente.
Para exportar um objeto grande para um arquivo do sistema operacional é chamada a função:
int lo_export(PGconn *conn, Oid lobjId, const char *nome_do_arquivo);
O argumento lobjId especifica o OID do objeto grande a ser exportado, e o argumento nome_do_arquivo especifica o nome do arquivo no sistema operacional. Deve ser observado que o arquivo é escrito pela biblioteca de interface cliente, e não pelo servidor. A função retorna 1 quando é bem-sucedida, ou -1 caso contrário.
Para abrir um objeto grande existente para ler ou escrever chama-se a função:
int lo_open(PGconn *conn, Oid lobjId, int modo);
O argumento lobjId especifica o OID do objeto grande a ser aberto. Os bits de modo controlam se o objeto deve ser aberto para leitura (INV_READ), escrita (INV_WRITE), ou ambos. O objeto grande não pode ser aberto antes de ser criado. A função lo_open retorna o descritor do objeto grande (não negativo) para uso posterior em lo_read, lo_write, lo_lseek, lo_tell e lo_close. O descritor é válido apenas pela duração da transação corrente. Quando a função não é bem-sucedida retorna -1.
A função
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
writes escreve len bytes de buf no descritor de objeto grande fd. O argumento fd deve ter sido retornado por uma chamada anterior a lo_open. A função retorna o número de bytes realmente escritos. Caso aconteça algum erro, retorna um valor negativo.
A função
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
lê len bytes do descritor de objeto grande fd colocando-os em buf. O argumento fd deve ter sido retornado por uma chamada anterior à função lo_open. A função retorna o número de bytes realmente lidos. Caso aconteça algum erro, retorna um valor negativo.
Para mudar a posição corrente de leitura ou de escrita associada ao descritor do objeto grande chama-se a função:
int lo_lseek(PGconn *conn, int fd, int deslocamento, int donde);
Esta função move o ponteiro de posição corrente do descritor de objeto grande, identificado por fd, para a nova posição especificada pelo argumento deslocamento. Os valores válidos para o argumento donde são SEEK_SET (procurar a partir do início do objeto), SEEK_CUR (procurar a partir da posição corrente), e SEEK_END (procurar a partir do fim do objeto). O valor retornado é o novo ponteiro de posição, ou -1 se não for bem-sucedida.
Para obter a posição corrente de leitura ou escrita do descritor de objeto grande chama-se a função:
int lo_tell(PGconn *conn, int fd);
O descritor de objeto grande pode ser fechado chamando a função
int lo_close(PGconn *conn, int fd);
onde o argumento fd é o descritor do objeto grande retornado pela função lo_open. Se for bem-sucedida, a função lo_close retorna zero. Se houver erro, retorna um valor negativo.
Todo descritor de objeto grande que permanecer aberto no final da transação será fechado automaticamente.
Para remover um objeto do grande do banco de dados chama-se a função:
int lo_unlink(PGconn *conn, Oid lobjId);
O argumento lobjId especifica o OID do objeto grande a ser removido. A função retorna 1 quando é bem-sucedida. No caso de erro retorna -1.
