Changes between Initial Version and Version 1 of WF/Conexaocommainframe

Timestamp:

07/24/07 15:01:38 (17 years ago)

Author:

trac

Comment:

--

WF/Conexaocommainframe

@@ +1 @@
+== 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 = wf_create_object("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();
+
+}}}
+
+----
+
+==== configureResultSet ====
+
+'''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->configureResultSet(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 configureResultSet 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 = wf_create_object("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.