= Conexão com Mainframe =
[[WikiInclude(WF/tableofcontents)]]

== Classe: wf_natural ==

Esta classe tem a finalidade de ler dados do ambiente mainframe realizando comunicação através do protocolo Jasppion (Java Active Server Page Package for Internet On Demand) desenvolvido pela CELEPAR.

=== Métodos ===

=== configure ===

'''Descrição:''' Realiza a configuração básica do objeto.

'''Parâmetros:'''

  $subProgram: Sub-programa nature que será executado no mainframe (8 bytes).

  $inputParameter: Parâmetro de entrada para execução do sub-programa no mainframe.

  [$ip]: Endereço IP da máquina mainframe. ex: 10.15.61.10.

  [$port]: Porta que receberá a requisição no mainframe. ex: 0316.

  [$key]: Chave de 8 bytes (usuário) que fornece acesso ao top secret (mainframe). Padrão atual: N000 + parâmetro + espaço.

  [$password]: Senha para a chave (também de 8 bytes).

  [$environment]: Ambiente onde está localizado o sub-programa. 'D' (desenvolvimento) ou 'P' (produção).

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$natural = $this->factory->getInstance("wf_natural");

$natural->configure("SUBPROGR", "senha", "10.15.61.10", 0316, "SUB", "SENHA", 'D');
}}}

----

=== setDBGatewayProtocol ===

'''Descrição:''' Realiza a escolha do formato da transação (DBCon ou DBGateway) no mainframe, utilizando o protocolo Jasppion.

'''Formato DBCon:'''

Esta transação executa no mainframe um programa chamado JASPIN. É um tipo de chamada mais performática, visto que está limitado a 32Kb de transferência de dados, limitação do DBCon. A partir do momento em que o DBCon passar a tratar mais que 32Kb o JASPIN automaticamente irá tratar este tamanho. O JASPIN não tem limitação de tamanho de dados.

'''Formato DBGateway:'''

Esta transação executa no mainframe um programa chamado JASPPION. É um tipo de chamada menos performática, visto que  ela devolve uma quantidade ilimitada de registros de dados, uma vez que o JASPPION não tem limitação de tamanho de dados.  No mainframe cada registro formatado no sub-programa natural como se fosse uma linha de um Record Set e é devolvido ao requisitante.

'''Parâmetros:'''

  [$dbGateway]: Por default, o formato da transação é DBCon, a não ser que este seja alterado através da chamada do método setDBGatewayProtocol(). Se for necessário retornar ao formato DBCon, pode-se setar este parâmetro para false quando o método for invocado.

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$natural->setDBGatewayProtocol();
}}}

'''Exemplo de uso (2):'''

{{{
$this->natutal->getMSG();

$natural->setDBGatewayProtocol(false); // Seta formato de transação para DBCon
}}}

----

=== execute ===

'''Descrição:''' Conecta ao mainframe e captura os dados requisitados

'''Parâmetros:''' <nenhum>

'''Retorno''': booleano

'''Exemplo de uso:'''

{{{
$natural->execute();
}}}

----

=== getRC ===

'''Descrição:''' Retorna o código do erro ocorrido durante a requisição. Se o retorno for zero nenhum erro ocorreu.

'''Parâmetros:''' <nenhum>

'''Retorno''': Integer

'''Exemplo de uso:'''

{{{
$natural->getRC();
}}}

----

=== getMSG ===

'''Descrição:''' Retorna a explanação do erro quando o getRC() é diferente de zero.

'''Parâmetros:''' <nenhum>

'''Retorno''': String

'''Exemplo de uso:'''

{{{
$natural->getMSG();
}}}

----

=== getDataParameter ===

'''Descrição:''' Retorna os dados obtidos do mainframe em formato String (formato devolvido pelo mainframe)

'''Parâmetros:''' <nenhum>

'''Retorno''': String

'''Exemplo de uso:'''

{{{
$natural->getDataParameter();
}}}

----

=== configure!ResultSet ===

'''Descrição:''' Para facilitar a manipulação dos dados (originalmente em string), pode ser configurado um !ResultSet para execução de cada sub-programa no mainframe.

'''Parâmetros:'''

  [$lineSize]: Tamanho de cada linha retornada pelo mainframe, normalmente o tamanho é fixado em 200 bytes.

  [$rowConf]: Array de configuração do !ResultSet. Deve ser passado o nome do campo (para identificação de cada atributo, já que o mainframe não retorna esta informação) como chave e o tamanho (quantidade de caracteres - em tamanho fixo) como valor.

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$natural->configure!ResultSet(200, array("id" => 5, "nome" => 30) );
}}}

----

=== !ResultSet ===

!ResultSet é um objeto que pode ser acessado através da classe wf_nature e que é construído após o método configure!ResultSet ser invocado.

=== Métodos ===

=== getNextRow ===

'''Descrição:''' Retorna a próxima linha dentro do set de registros

'''Parâmetros:''' <nenhum>

'''Retorno''': Array contendo uma linha de registros

'''Exemplo de uso:'''

{{{
$row = $natural->ResultSet->getNextRow();

echo $row['id']; // O mesmo resultado pode ser obtido utilizando o método getFieldByName.
}}}

----

=== getFieldByName ===

'''Descrição:''' Captura dado de um campo específico da linha corrente no !ResultSet

'''Parâmetros:''' <nenhum>

'''Retorno''': String com dado solicitado

'''Exemplo de uso:'''

{{{
$natural->ResultSet->getNextRow();

echo $natural->resultSet->getFieldByName("id");
}}}

----

=== Exemplo de uso completo ===

{{{
/ *
 * Neste exemplo o formato de arquivo retornado pelo mainframe contém 2 campos de tamanho 5 e 30, respectivamente.
 * Considera-se também que cada linha tem 200 caracteres
 */
$natural = $this->factory->getInstance("wf_natural");
$natural->configure("SUB_PROG", "");
$natural->setDBGatewayProtocol();
$natural->execute();

// Se não contém nenhum erro

if (!$natural->getRC())

    // Captura a string retornada pelo mainframe

    $result = $natural->getDataParameter();

    // Configura ResultSet para manipular os dados

    $natural->configureResultSet(200, array("id" => 5, "nome" => 30) );

    // Captura os dados

    while ($natural->resultSet->getNextRow()){
        echo $natural->resultSet->getFieldByName("id");
        echo $natural->resultSet->getFieldByName("nome");
    }

} else {

    $error = $natural->getMSG();

}

}}}

----

'''OBS''': [] identificam os parâmetros opcionais