2 SIP2PHP

Versione 1.0

2007-8 - Caspur, Dip. Di Fisica Universit di Roma Sapienza, Polo SBN RMS

Note Legali

Introduzione
SIP2PHP una libreria di funzioni php per la creazione, linvio, la ricezione e linterpretazione di messaggi SIP2. Questo manuale offre una descrizione completa dei contenuti del pacchetto SIP2PHP per un corretto uso delle funzioni php in esso presenti e della sua configurazione. Si assume che il lettore di questo manuale sia a conoscenza del funzionamento dello Standard Interchange Protocol della 3M e che quindi abbia letto i manuali di riferimento rilasciati dalla 3M, o dei testi equivalenti.

Installazione
SIP2PHP richiede un'installazione minima. Il modulo va configurato secondo le proprie esigenze e posizionato nella cartella desiderata del vostro Web-Server. Es.: http://www.mywebserver.it/SIP2PHP/. Per usare le funzioni di invio e ricezione dei messaggi SIP2 bisogna prima configurare l'indirizzo del server SIP2 e la porta a cui collegarsi del modulo. Se si desidera fare uso del file di log controllare che i privilegi del file log/log.dat o del file di log esterno scelto, siano impostati su 755. Una volta completata linstallazione del modulo caricate il file ./sip2php.php per accedere alle sue funzioni. Per testare il funzionamento di queste librerie possibile visionare i files desempio contenuti nella cartella docs/examples/. Per maggiori informazioni passate al capitolo Esempi Pratici, in coda a questo manuale. Requisiti minimi:
- Connessione alla rete. - Servizio SIP2. - PHP 5 o superiore, installato. - Apache 2.x o Microsoft IIS 6.x.

Nota: Per una personalizzazione stabile del modulo si consiglia vivamente di non usare metodi differenti da quelli descritti in questo manuale e di non alterare perci la struttura portante del modulo.

Configurazione
La configurazione del modulo SIP2PHP risiede nella cartella ./config/ ed composta da quattro files: config.default.php, fields_patterns.inc.php, files_paths.inc.php, msg_structures.inc.php. Di questi files, config.default.php contiene la configurazione predefinita ed il solo file da cui attingere per la personalizzazione del modulo.

1 - fiies_paths.inc.php 2 - configure.php vuoto 3 - config.default.php 4 - fields_patterns.inc.php 5 - msg_structures.inc.php

Percorsi ai documenti del modulo. Configurazione locale. Configurazione predefinita. Espressioni regolari dei formati dei campi SIP2. Struttura dei messaggi SIP2

1 - Percorsi assoluti e percorsi relativi

Il documento di configurazione dei percorsi ./confg/files_paths.inc.php definisce con delle costanti i nomi dei documenti e delle cartelle che compongono il modulo SIP2PHP e i conseguenti percorsi assoluti agli stessi. I valori predefiniti di queste costanti non richiedono modifiche.

SIP2_ABPATH SIP2_DATA_LOCAL SIP2_DATA_DEFAULT SIP2_DATA_STRUCT SIP2_DATA_PATTRS SIP2_FILE_LIB SIP2_FILE_REQ SIP2_FILE_RES SIP2_FILE_CLT

Percorso assoluto a questo modulo. File di configurazione locale. File di configurazione predefinita. File delle strutture dei messaggi SIP2. File contenente le espressioni regolari dei formati dei campi SIP2. Classe di funzioni base. Classe di funzioni per la creazione di messaggi SIP2. Classe di funzioni per linterpretazione dei messaggi SIP2. Classe di funzioni per linvio e la ricezione dei messaggi SIP2, e per la gestione del file di log. Il file di log predefinito. File per laccesso al test del modulo. Cartella dei files di configurazione. Cartella delle classi di funzioni del modulo. Cartella del file di log predefinito. Cartella del programma di test. Cartella di documentazione. Percorso assoluto al file di configurazione locale. Percorso assoluto al file di configurazione predefinita. Percorso assoluto al file delle espressioni regolari. Percorso assoluto al file delle strutture dei messaggi. Percorso assoluto alla classe principale. Percorso assoluto alla classe per la creazione dei messaggi. Percorso assoluto alla classe per linterpretazione dei messaggi. Percorso assoluto alla classe per linvio e ricezione dei messaggi.

SIP2_FILE_LOG SIP2_FILE_TEST SIP2_DIR_CONF SIP2_DIR_LIB SIP2_DIR_LOG SIP2_DIR_TEST SIP2_DIR_DOC SIP2_PATH_LCONFIG SIP2_PATH_DCONFIG SIP2_PATH_PATTR SIP2_PATH_STRUC SIP2_PATH_LIB SIP2_PATH_REQ SIP2_PATH_RES SIP2_PATH_CLT

SIP2_PATH_LOG

Percorso assoluto al file di log predefinito.

2 - Configurazione locale
Il documento di configurazione locale ./configure.php vuoto di default. Il contenuto di configure.php pu e deve essere copiato esclusivamente dai contenuti del documento config/config.default.php che conserva le variabili di configurazione generale. I valori immessi andranno a sostituire quelli di ./config/config.default.php, lasciando questultimo intatto.

3 - Configurazione predefinita
Il file ./config/config.default.php definisce un insieme di variabili per una gestione flessibile delle librerie. Un array associativo le raccolglie sotto gli indici: CFG, LOC, DFV e PFV. $sip2cfg [CFG] $sip2cfg [LOC] $sip2cfg [DFV] $sip2cfg [PFV] Configurazione generale Configurazione delle Locali di Sistema Configurazione dei valori predifiniti dei campi SIP2 Configurazione dellinterpretazione dei campi SIP2

Configurazione Generale Lindice CFG della variabile $sip2cfg contenuta nel file ./config/config.default.php conserva i dati generici per configurazione delle librerie di questo modulo. In fase di configurazione, il programma provvede a definire costanti del valore associato a ciascuno dei seguenti indici finali. Il nome di ciascuna costante quello dellindice del quale conserver il valore, con laggiunta in testa del prefisso SIP2_.

Esempio: $sip2cfg [CFG] [SERVER_IP] => SIP2_SERVER_IP = ip del server SIP2.

Nota: I valori dellarray $sip2cfg[CFG] servono solo come riferimento per la creazione delle costanti di cui sopra. Una volta definite tali costanti il modulo non far pi uso della variabile $sip2cfg [CFG].

Indici contenuti nellarray $sip2cfg [CFG]:

( SIP2_ ) DATE_LOCALE bool Valore della costante locale per la personalizzazione della data nel formato locale. Vedi PHP setlocale() per maggiori chiarimenti. Formato della data in PHP strftime(). Il carattere delimitatore dei campi dei messaggio SIP2 (request e response). Non modificare. Aggiunge in fase di costruzione i campi AY e AZ ai messaggi SIP2 (request). Il carattere delimitatore interno ai campi dei messaggi SIP2 (request e response). Conserva il valore dei campi dei messaggi inviati. Usa come file di log il path indicato da LOG_EXPATH . Path al file di log preferenziale.

( SIP2_ ) DATE_FORMAT int ( SIP2_ ) DELIMITER char

( SIP2_ ) ERROR_DETECTION bool

( SIP2_ ) INNER_DELIMITER char

( SIP2_ ) KEEP_FIELDS bool ( SIP2_ ) LOG_EXTERNAL bool ( SIP2_ ) LOG_EXTPATH string

( SIP2_ ) LOG_LENGTH int

Dimensione massima del file di log prima di essere troncato. Salva le transazioni effettuate sul file di log. Lunghezza massima dei messaggi SIP2 in lettura. Set di caratteri per la conversione delle date. Numero massimo di tentativi per linvio e la ricezione di messaggi. Valore di partenza del campo sequence number. IP del server SIP2. Porta del server SIP2. Tempo massimo di attesa per linvio socket. Tempo massimo di attesa per la ricezione socket. Impostando su true il campo summary pu essere definito con una singola cifra da 1 a 10, che rappresenta la posizione della Y fra i dieci spazi vuoti del valore del campo. Per chiarimenti vedere il manuale SIP2 Developers Guide, descrizione del campo summary. Il carattere con cui debbono terminare I messaggi SIP2 (request e response). Non modificare.

( SIP2_ ) LOG_SAVE bool ( SIP2_ ) MSG_LENGTH int ( SIP2_ ) OUT_CHARSET string ( SIP2_ ) RETRIES int

( SIP2_ ) SEQUENCE_NUMBER int ( SIP2_ ) SERVER_IP string ( SIP2_ ) SERVER_PORT string ( SIP2_ ) SO_SNDTIMEO string ( SIP2_ ) SO_RCVTIMEO string ( SIP2_ ) SUMMARY_INTERACT bool

( SIP2_ ) TERMINATOR char

Configurazione delle Locali di Sistema Lindice LOC della variabile $sip2cfg contenuta nel file ./config/config.default.php conserva un array di Locali di Sistema. Per ciascuna Locale inserita nellarray il programma ne tenta lattivazione. Per la scelta delle giuste Locali vedi il manuale online PHP, funzione setlocale(). Locali di default:
$sip2cfg[LOC][] = italian; $sip2cfg[LOC][] = it_IT; Lingua italiana su Windows. Lingua italiana su Apache.

Configurazione dei valori predefiniti dei campi SIP2 Lindice DFV della variabile $sip2cfg contenuta nel file ./config/config.default.php conserva i valori predefiniti opzionali dei campi dei messaggi SIP2 (request) che andranno a rimpiazzare i campi lasciati volutamente vuoti in fase di formattazione del messaggio SIP2. Per la modifica inserire dati appropriati a ciascun campo attenendosi strettamente alle

specifiche del manuale SIP2. Ai valori predefiniti dei campi dei messaggi SIP2 (request) ha la precedenza qualunque valore degli stessi campi, immesso durante la formattazione del messaggio, purch questultimo non sia una stringa vuota.
Nota: Il file config.default.php contiene solo la dichiarazione dellarray, linserimento dei suoi valori attraverso luso del file configure.php opzionale e non comporta delle insufficienze nella configurazione dello script.

Indici dellarray $sip2cfg [DFV]:

card_retained, currency_type, fee_type, hold_mode, language, max_print_width, nb_due_date, no_block, payment_type, protocol_version, psw_algorithm, renewal_policy, status_code, summary, third_party_allowed, uid_algorithm, AA, AB AC, AD, AJ, AL, AO, AP,

BI, BK, BO, BP, BQ, BS, BW, BY, CG, CH, CN, CO, CP

Configurazione dellinterpretazione dei campi SIP2 Lindice PFV conserva un array di valori di interpretazione di messaggi SIP2 (response). A ciascun indice nome_del_campo viene associato un array associativo i cui indici sono i valori che il campo pu restituire. Per la personalizzazione di queste interpretazioni, a ciascuno di questi indici va associato un nuovo valore: Esempio: $sip2cfg[PFV][nome_del_campo][valore del campo] = interpretazione del valore del campo. Alcuni campi SIP2 non permettono una interpretazione lineare dei loro valori. Due campi speciali sono ad esempio il campo BX e il campo patron status, che vengono interpretati come una collezione di valori. Nei messaggi SIP2 questi campi sono costituiti da stringhe di dimensioni fisse, composte da combinazioni di due soli caratteri. Il campo BX ad esempio composto da una stringa di 16 caratteri, ognuno dei quali rappresenta lo stato di un messaggio SIP2. Laccoppiata posizione/carattere determina cio se un messaggio SIP2 stato abilitato dal server oppure no. Personalizzare uno di questi due campi significa assegnare un valore ad ogni posizione dellarray $sip2cfg[PFV][BX] o $sip2cfg[PFV][patron_status]. Quando il messaggio SIP2 verr processato, linterprete del campo BX o patron status provveder a restituire un array contenente tutte le posizioni posizioni attive e il relativo messaggio. Per chiarimenti sulla struttura dei messaggi SIP2 e per la comprensione dei singoli campi componenti, riferirsi al manuale della 3M.

4 - Espressioni regolari dei formati dei campi SIP2

Il file ./config/fields_patterns.inc.php contiene una costante per ogni campo del protocollo SIP2. Ogni costante conserva lespressione regolare del formato del campo da cui prende il nome. Queste costanti sono usate dalle funzioni di interpretazione dei messaggi SIP2 per riconoscere e scomporre i messaggi SIP2. La modifica sconsigliata.

5 - Struttura dei messaggi SIP2

Il file ./config/msg_structures.inc.php contiene un array associativo dei messaggi SIP2 (request e response) e dei campi che li contraddistinguono. I valori espressi in questo array vengono usati dalle funzioni di creazione, scomposizione e interpretazione dei messaggi SIP2. La modifica fortemente sconsigliata.

Classi di funzioni
Le librerie di funzioni del modulo SIP2PHP sono raggruppate in quattro classi distinte. Una classe base si occupa di caricare le variabili di configurazione e di includere automaticamente il codice delle altre tre classi. Queste ultime provvedono a fornire tutte le funzioni necessarie per costruire, trasmettere, ricevere ed interpretare messaggi SIP2. Le funzioni di trasmissione e ricezione dei messaggi SIP2 lavorano su connessioni socket.

1 - sip2php() 2 - sip2request()

sip2php.class.php Classe base sip2req.class.php Classe per la creazione dei messaggi. Classe per linterpretazione dei messaggi. Classe per linvio e la ricezione dei messaggi.

3 - sip2response() sip2res.class.php 4 - sip2socket() sip2sok.class.php

1 - Classe sip2php()
Carica la configurazione del modulo SIP2PHP. Detiene alcune funzioni di generiche di base. Include inoltre automaticamente le altre classi di funzioni del modulo.

file:

./lib/sip2php.class.php

require:

./config/config.default.php
./config/msg_structures.inc.php ./config/fields_patterns.inc.php ./lib/sip2req.class.php ./lib/sip2res.class.php ./lib/sip2sok.class.php

vars:
public static $default_values array public static $msg_structure array public static $parsing_values array public static $seq_number int Valori di default dei campi SIP2 (request). Strutture dei messaggi SIP2. Array delle interpretazioni dei campi dei messaggi SIP2. SIP2 Sequence number.

methods:
construct __construct ( )
Carica la configurazione del modulo e include le classi di funzioni SIP2PHP. return void

public transaction ( string $msg_code, array $fields_values = array(), bool $autoclose = false, int $sst = NULL, int $srt = NULL ) Formatta e invia un messaggio SIP2 di codice $msg_code, quindi riceve e interpreta il messaggio di ritorno.
param $msg_code string param $fields_values array Stringa numerica contenente un codice SIP2. Array associativo dei valori dei campi del messaggio numero $msg_code. A ricezione effettuata chiude automaticamente la connessione socket. timeout della trasmissione socket in uscita. timeout della trasmissione socket in entrata.

param $autoclose bool param $sst int param $srt int

return mixed int

ritorna 0 ad operazione effettuata. Ritorna un numero da 1 a 4 se loperazione si arresta in una delle sue fasi:

1 2 3 4

formattazione. invio e ricezione. scomposizione. interpretazione.

public trace_errors ( string $error, int $errlevel ) Ad ogni chiamata di questo metodo, aggiunge un indice alla variabile di classe $err = array() e lo associa ad un array contenente la data corrente, il messaggio di errore $error e il livello di errore indicato dal parametro $errlevel.
param $string string param $errlevel int Stringa contenente un messaggio SIP2. In questa versione di SIP2PHP sono abilitati i livelli 1 e 0. 0 - Fatal Error. 1 - Notice. 2 - Fatal Error.

return void

public check_message ( string $string ) Esamina larchitettura della stringa $string e ne verifica la validit come messaggio SIP2.
param $string string return bool Stringa contenente un messaggio SIP2. Restituisce true se $string un valido messaggio SIP2, false alrimenti.

public check_msgcode ( string $string ) Data una stringa $string estrapola i primi due caratteri che la compongono e verifica che la selezione costituisca il codice di identificazione di un messaggio SIP2. Se la selezione un valido codice di identificazione la funzione restituisce il suo valore, altrimenti ritorna false.
param $string string return mixed bool/string 2 char Stringa contenente un messaggio SIP2. Restituisce il codice del messaggio $string, false altrimenti.

public SIPseq_number () Incrementa il valore della variabile di classe $seq_number di 1 se il valore compreso tra 0 e 8, altrimenti lo riporta a zero.
return int Il valore di $seq_number.

public SIPdate () Restituisce la data corrente formattata secondo il protocollo SIP2.

return string Stringa rappresentante la data corrente nel formato SIP2.

public SIPchecksum ( string $inputstr ) Data una stringa $inputstr la funzione restituisce il suo checksum.
param $inputstr string La stringa di cui si vuole ottenere il checksum.

return string

Restituisce il checksum del parametro $inputstr.

public check_checksum ( string $msg ) Esamina la validit del checksum contenuto nel messaggio SIP2$msg. Se la stringa $msg non un valido messaggio SIP2, restituisce false.
return bool Restituisce true se il checksum valido, false altrimenti.

2 - Classe sip2request()
Contiene tutte le funzioni necessarie la creazione e la formattazione di messaggi SIP2 (request). sip2request() si appoggia ai metodi della classe sip2php(), pertanto non pu essere invocata da sola.

file:

./lib/sip2req.class.php

require:

./lib/sip2php.class.php

vars:
private static $fields array public static $msg string Istanza dei campi del messaggio SIP2 (request) da formattare. Istanza della stringa contenente il messaggio SIP2 formattato.

methods:
public formatMSG ( string $msg_code, array $fields_values ) Produce la stringa del messaggio SIP2 numero $msg_code, usando i come valore dei campi, i valori associati agli indici di $fields_values o, alternativamente, i valori predefiniti corrispondenti. I valori di $fields_values devono seguire le specifiche SIP2 e devono essere associati al nome del campo appropriato.
param $fields_values array return string Array associativo dei campi del messaggio SIP2 da formattare. Restituisce il messaggio SIP2 pronto per linvio allACS.

private get_transaction_date ( ) Funzione ausiliaria del metodo formatMSG(). Esamina la variabile di classe $fields['transaction_date']. Se il suo contenuto nullo o vuoto, riassegna alla variabile il valore della data corrente formattata secondo protocollo. Se invece il suo contenuto non una valida data SIP2 salva un messaggio di errore nella variabile sip2php:$err e riassegna alla variabile il valore della data corrente formattata secondo protocollo.
return void

private get_return_date ( ) Funzione ausiliaria del metodo formatMSG(). Esamina la variabile di classe $fields[return_date']. Se il suo contenuto nullo o vuoto, riassegna alla variabile il valore della data corrente formattata secondo protocollo. Se invece il suo contenuto non una valida data SIP2 salva un messaggio di errore nella variabile sip2php:$err e riassegna alla variabile il valore della data corrente formattata secondo protocollo.
return void

private get_NB_due_date ( ) Funzione ausiliaria del metodo formatMSG(). Esamina la variabile di classe $fields[nb_due_date']. Se il suo contenuto nullo o vuoto, riassegna alla variabile il valore della data corrente formattata secondo protocollo. Se invece il suo contenuto non una valida data SIP2 salva un messaggio di errore nella variabile sip2php:$err e riassegna alla variabile il valore della data corrente formattata secondo protocollo.
return void

public get_summary ( ) Funzione ausiliaria del metodo formatMSG(). Esamina la variabile di classe $fields['summary '] e ne modifica eventualmente il contenuto nei seguenti casi: Se un intero compreso tra 0 e 9, produce e riassegna alla variabile $fields['summary '] una stringa di 10 caratteri, di cui 9 saranno vuoti (\s) e uno solo uguale a Y. La posizione del carattere Y allinterno della stringa sar determinata dallintero di cui sopra. Se il contenuto di $fields['summary '] vuoto o nullo, le verr riassegnato come valore una stringa di 10 caratteri vuoti. Se il contenuto di $fields['summary '] non risponde ai casi sopra descritti, n un valido campo summary,
return void

private get_error_detection_fields ( string $str ) Completa il messaggio SIP2 con laggiunta in coda dei campi di sequence number e checksum ( AY, AZ ).
param $str string return string Il messaggio formattato privo dei campi error detection. Ritorna $str con i campi di error detection appesi in coda.

3 - Classe sip2response()
Funzioni per la scomposizione e interpretazione dei messaggi SIP2 (response). sip2response() si appoggia ai metodi della classe sip2php(), pertanto non pu essere invocata da sola.

file:

./lib/sip2res.class.php

require:

./lib/sip2php.class.php

vars:
private static $fields array Array associativo che conserva i valori dei campi del messaggio inviato dall'ACS. Il messaggio SIP2 trasmesso dall'ACS scomposto in un array associativo. Array associativo che conserva linterpretazione dei campi del messaggio ricevuto.

public static $split array

public static $parsed array

methods:
construct __construct ()
Se il valore della costante SIP2_ERROR_DETECTION false elimina dalla struttura dei messaggi SIP2 ( sip2php::$msg_structures ) i campi di error detection ( AY, AZ). return void

public splitMSG ( string $acs_msg ) Se il parametro $acs_msg una stringa il cui valore un valido messaggio SIP2 di risposta, la funzione tenta la scomposizione del messaggio SIP2 nei campi che lo compongono. Salva larray ottenuto nella variabile di classe $split.
param $acs_msg string return mixed bool/array Messaggio SIP2 (response). Se il parametro $acs_msg un valido messaggio di risposta restituisce un array associativo dei campi che lo compongono, false altrimenti.

public parse_fields ( array $array ) Dato il parametro $array contenente un messaggio SIP2 precedentemente scomposto in un array associativo dei campi che lo compongono, ottenuto attraverso la funzione di classe splitMSG(), il metodo provvede a interpretarne i valori. I valori interpretati vengono inseriti nella variabile di classe $parsed. Per ogni interpretazione inserita in $parsed, lindice assegnato sar il nome del campo corrispondente.
param $array array Array associativo ottenuto tramite la funzione splitMSG().

return array

Array associativo dei valori dei campi interpretati.

public parseDigit ( string $str ) Ritorna la stringa $str priva di eventuali zero in testa, se $str non null. Se $str null restituisce 0.
param $str string return int Un intero >= 0.

public parseBX ( string $str ) Data la stinga del campo BX di un messaggio SIP2, per ogni Y in essa presente, popola larray $parsed[BX] dei valori di parsing presenti nella variabile sip2php::parsing_values[BX] corrispondenti alla posizione che tale Y occupa nella stringa. Per conoscere la definizione estesa del campo BX consultate il documento SIP2 Developers Guide della 3M, gi presente nella deocumentazione di questo software.
param $str string return array Il valore del campo BX. Array dei valori interpretati del campo BX.

public parsePatronStatus ( string $str ) Data la stinga del campo patron_status di un messaggio SIP2, per ogni Y in essa presente, popola larray $parsed[patron_status] dei valori di parsing presenti nella variabile sip2php::parsing_values[paron_status] corrispondenti alla posizione che tale Y occupa nella stringa. Per conoscere la definizione estesa del campo patron_status, consultate il documento SIP2 Developers Guide della 3M, gi presente nella deocumentazione di questo software.
param $str string return array Il valore del campo patron status. Array dei valori interpretati del campo patron status.

public parseCirculationStatus ( string $str ) Inserisce in $parsed[circulation_status] linterpretazione del parametro $str, valore del campo circulation status.
param $str string return string Il valore del campo circulation status. Valore interpretato del campo circulation status.

public parseTransactionDate ( string $str ) Inserisce in $parsed[transaction_date] una stringa di interpretazione del parametro $str, valore del campo transaction date. La data verr interpretata in base alla configurazione del modulo tramite le costanti SIP2_DATE_LOCALE, SIP2_DATE_FORMAT e SIP2_OUT_CHARSET.
param $str string return string Il valore del campo transaction date. Riformattazione del valore del campo transaction date.

4 - classe sip2socket()
Funzioni per linvio e la ricezione di messaggi SIP2. sip2socket() si appoggia ai metodi della classe sip2php(), pertanto non pu essere invocata da sola.

file:

./lib/sip2sok.class.php

require:

./lib/sip2php.class.php

vars:
public static $link resource public static $request string public static $response string public static $retries string Connessione socket. Messaggio trasmesso allSC. Messaggio trasmesso dallACS. Contatore dei tentativi di trasmissione e ricezione.

methods:
construct __construct ( bool $connect_on_load = true ) Se il valore di $connect_on_load true tenta di stabilire una connessione socket al server SIP2.
param $connect_on_load bool return void Default true. Connessione automatica al server SIP2.

private getTerminalInfo ( bool $encode = false ) Raccoglie in una stringa informazioni sul terminale dal quale vengono effettuate le transazioni. Se $encode true le informazioni vengono criptate in base 64. La funzione tenter di raccoglier le seguenti informazioni: - Il server sotto il quale sta girando il programma. - Il nome della macchina dalla quale si sta operando. - Il sistema operativo e il browser della macchina dalla quale si sta operando. - Lo script in corso.
param $encode bool return string Default false. Cripta le informazioni. Restituisce una stringa di informazioni sul terminale.

public openSocketConnection ( ) Tenta di aprire una connesione socket al server SIP2_SERVER_IP su porta SIP2_SERVER_PORT. Nel caso non sia possibile effettuare la connessione, il metodo restituisce un messaggio di errore di tipo SIP2_LIB_ERRORS (default: E_USER_NOTICE). A connessione effettuata la variabile di classe $link ne conserver il valore.

Se SIP2_LOG_SAVE true verr indicato sul file di log lavvio della connessione.
return bool Restituisce true a connessione effettuata, false altrimenti

public closeSocketConnection ( ) Chiude la connessione socket precedentemente registrata sulla variabile di classe $link. Se SIP2_LOG_SAVE true verr indicato sul file di log linterruzione della connessione.
return void

public send_and_retrive ( string $msg, bool $autoclose = false, string $socket_send_timeout = NULL, $socket_recive_timeout = NULL ) Il metodo send_and_retrive() provvede allinvio e alla ricezione via socket, di messaggi SIP2 in ununica azione. Se la variabile di classe $link false, la funzione tenta una connessione allACS invocando la funzione di classe openSocketConnection(). Dopo un numero massimo di tentativi di invio e ricezione dei messaggi pari a SIP2_RETRIES, in caso di mancato invio o di mancata ricezione e nel caso il messaggio di risposta non sia quello che ci si aspettava, la funzione restituisce false.
param $msg string param $autoclose bool param $socket_send_timeout int Stringa contenente un messaggio SIP2 (request). Chiude la connessione allACS a invio e ricezione effettuati. Se dato assegna la durata del parametro della funzione PHP socket_set_option(), SO_SNDTIMEO. Se dato assegna la durata del parametro della funzione PHP socket_set_option(), SO_RCVTIMEO. Se loperazione andata a buon fine restituisce una stringa contenente il messaggio SIP2 di risposta, inviato dal server, altrimenti false.

param $socket_recive_timeout int

return mixed bool/string

public savelog ( int $op = NULL ) Se SIP2_LOG_SAVE true il metodo si prepara a salvare su file I dati definiti dal parametro opzionale $op. Se inoltre SIP2_LOG_EXTERNAL true il file di log sar quello indicato da SIP2_LOG_EXTPATH. Se viene definito un file di log esterno inesistente il metodo si preoccuper di crearlo. Con param $op = 0 la funzione segner sul file di log la chiusura della connessione socket; Con param $op = 1 la funzione segner sul file di log lapertura della connessione socket; Con param $op = 2 la funzione segner sul file di log I dati relativi alla transazione SIP2 effettuata; In caso di impossibilit di lettura, scrittura o creazione del file di log, il metodo restituisce un messaggio derrore di tipo SIP2_LIB_ERRORS (default: E_USER_NOTICE).
return void

Tracciatura delle operazioni SIP2 e gestione degli errori

Il modulo SIP2PHP prevede lutilizzo di funzioni per la tracciatura delle operazioni SIP2 e una gestione minima degli errori. La tracciatura delle operazioni SIP2 possibile solo abilitando lopzione corrispondente nel file di configurazione e permette di salvare su di file le transazioni SIP2 eseguite, nonch conservare informazioni sul terminale che le ha effettuate. Luso di un file di Log utile per rilevare eventuali errori non individuali altrimenti. Il codice del programma prevede inoltre una tracciatura degli errori che si possono verificare in caso di costruzione, interpretazione, invio e ricezione di un messaggio SIP2. Questi errori vengono conservati per la sola durata dello script, nella variabile sip2php::$err.

1 - Tracciatura delle operazioni SIP2 2 - Gestione degli errori

1 - Tracciatura delle transizioni SIP2

Attraverso la lettura del file di log possibile accedere alla storia delle varie transizioni e delle varie operazioni svolte dal modulo dal momento della connessione al server SIP2. Per una registrazione corretta della storia delle transazioni bene usare le funzioni definite in sip2client(). default file: ./log/log.php

Il file di log conserva I dati salvati in pi stringhe distinte a seconda del tipo di operazione registrata. Le stringhe sono identificate con un prefisso intellegibile.

Apertura della connessione Le funzioni di connessione e invio e ricezione dei messaggi SIP2 della classe sip2client() prevedono innanzi tutto la registrazione sul file di log dellavvenuta connessione al server SIP2. Es.:
TERMINAL: xxxx.xxxxx#xxxx.xxxxx#xxxxxxx/x.x (xxxxxxxxx; x; xxxxx xxx xx x; xx-xx; xx:x.x.x.xx) xxxxx/xxxxxxxx xxxxxxx/x.x.x.xx#/~x/xxxx/xxxx/xxxxx/xxxx/xxxx.xxx connection opened: Mon, 09 Feb 2008 10:15:28 +0200

Il prefisso terminal seguito dalla stringa di informazioni relative al terminale dal quale stata effettuata la connessione. In ordine: SERVER NAME, HTTP HOST, HTTP USER AGENT e SCRIPT NAME. Il prefisso conn opened gi assume lesito delloperazione. A seguire la data e lora in cui loperazione stata effetuata.

Chiusura della connessione Sebbene la connessione socket creata dalla funzioni sip2client ::send_and_recive() si chiuda automaticamente alla fine dellesecuzione dello script, possibile usando la funzione sip2client::closeSocketConnection() effettuare una chiusura manuale della connessione socket a transizione/i conclusa e automaticamente salvare sul file di log lavvenuta chiusura di tale connessione. Es.:
xxxx.xxxxx#xxxx.xxxxx#xxxxxxx/x.x (xxxxxxxxx; x; xxxxx xxx xx x; xx-xx; xx:x.x.x.xx) TERMINAL: xxxxx/xxxxxxxx xxxxxxx/x.x.x.xx#/~x/xxxx/xxxx/xxxxx/xxxx/xxxx.xxx Mon, 09 Feb 2008 10:15:30 +0200 connection closed:

Il prefisso TERMINAL seguito dalla stringa di informazioni relative al terminale dal quale stata effettuata la connessione. In ordine: SERVER NAME, HTTP HOST, HTTP USER AGENT e SCRIPT NAME. Il prefisso conn closed gi assume la conclusione delloperazione. A seguire la data e

lora in cui loperazione stata effetuata.

Tracciatura della transizione SIP2 La funzione sip2client ::send_and_recive() provvede in automatico ad aggiungere alla storia delle operazioni effettuate anche la transizione SIP2. Il file di log conserver quindi anche il messaggio inviato e la risposta conseguente. In questo caso il file di log apparir cos:
TERMINAL: xxxx.xxxxx#xxxx.xxxxx#xxxxxxx/x.x (xxxxxxxxx; x; xxxxx xxx xx x; xx-xx; xx:x.x.x.xx) xxxxx/xxxxxxxx xxxxxxx/x.x.x.xx#/~x/xxxx/xxxx/xxxxx/xxxx/xxxx.xxx TIME: Mon, 09 Feb 2008 10:15:29 +0200 REQUEST: 9900402.00AY1AZFCA4 RESPONSE: 98YYYNYN10000320080209 1015292.00AOcodice identificativo della biblioteca|AMnome della biblioteca|BXYYYYYYYYNNYNNNNN|ANSCLOCATION|AFConnessione su biblioteca xxxx effettuata |AGMessaggio di print_line inviato come ris|AGposta in seguito al messaggio SCStatus. |AGQuesto messaggio e' lungo 120 caratteri.|AG |AY1AZA18C

Il prefisso TERMINAL seguito dalla stringa di informazioni relative al terminale dal quale stata effettuata la connessione. In ordine: SERVER NAME, HTTP HOST, HTTP USER AGENT e SCRIPT NAME. Il prefisso TIME seguito dalla data e lora della transazione. Il prefisso REQUEST seguito dalla stringa del messaggio SIP2 cos come stato inviato allACS. Il prefisso RESPONSE seguito dalla stringa del messaggio SIP2 cos come stato inviato dallACS.

Nota: non detto che le date eventualmente presenti sulle stringhe dei messaggi SIP2 coincidano con la data registrata dallo script dopo il prefisso TIME. Nota: La prima stringa che fissa e contiene le informazioni relative al terminale, al browser e allo script che si sta usando durante la connessione al server SIP2 pu essere criptata impostando la costante SIP2_SAVE_LOG su true. le informazioni verranno criptate in base64.

2 - Gestione degli errori

Per tutta la durata dello script, SIP2PHP conserva in una delle sue variabili gli errori che eventualmente si possono presentare nel corso dellesecuzione di unoperazione. Questi errori vengono salvati nella variabile sip2php::$err, in forma di array, nel quale vengono registrati anche la data e il livello derrore. I dati raccolti nella variabile sip2php::$err non vengono in alcun modo riprodotti sullo schermo, rimangono a disposizione invece del programmatore che ne voglia fare uso in fase di debug, per le applicazioni che facciano uso di questo software. La variabile sip2php::$err un array multidimensionale. Per ciascuno dei suoi indici assegnato un array che conserva la data, il livello derrore e il testo del messaggio derrore. In questa versione gli errori possono essere di 3 livelli differenti: Notice, Warning e Fatal. Es. :
array ( [0] => array ( date => ... error => ... level => ... ), ...

// string: Data dellerrore in formato "Y/m/d H:i:s", // string: Testo del messaggio derrore // string: Livello derrore

);

Nota: Gli errori presi in considerazione dal programma sono esclusivamente quelli definiti allinterno delle funzioni per la creazione, linterpretazione, linvio e la ricezione di messaggi SIP2.

Esempi Pratici
Nella documentazione presente una cartella con alcuni esempi pratici di uso delle librerie SIP2. I file di esempio introducono alle funzioni di base per la creazione, linterpretazione e linvio dei messaggi SIP2. Gli esempi possono essere trovati nella directory ./docs/examples/ . Tutti I files di esempio contengono una parte di script per la stampa a schermo di eventuali errori rilevati dal programma.

0 - Accenni sulla composizione dei messaggi SIP2 1 - Formattazione 2 - Scomposizione 3 - Interpretazione 4 - Invio e ricezione 5 - Eseguire una transazione completa, parte 1 6 - Eseguire una transazione completa, parte 2 file: example_01.php file: example_02.php file: example_03.php file: example_04.php file: example_05.php file: example_06.php

Nota: example_04.php, example_05.php e example_06.php producono a tutti gli effetti una transizione SIP2. Assicurarsi di aver inserito lindirizzo e la porta del server SIP2 nel file di configurazione locale per poter utilizzare e testare questi script.

0 - Accenni sulla composizione dei messaggi SIP2

Un messaggio SIP2 una stringa di lunghezza massima pari a 8192 caratteri la cui struttura scomponibile in tre sottostringhe contenenti ciascuna un gruppo di valori, detti campi del messaggio, e terminante con un carattere di terminazione, generalmente carriage return ( \r ). La prima delle sottostringhe contiene i campi obbligatori del messaggio, la seconda sottostringa contiene i campi opzionali del messaggio e la terza sottostringa contiene invece i campi di error detection. Questi ultimi sono anchessi obbligatori se il server ne fa uso. Es.: 1720080103 080009AOid dellistituto|ABcodice inventario|AC|AY1AZEADD\r
a - Campi obbligatori: b - Campi opzionali: c - Campi di error detection: 1720080103 080009 AOid dellistituto|ABcodice inventario|AC| AY1AZEADD

a - A partire dal codice numerico del messaggio in testa alla stringa, i campi obbligatori si succedono secondo un ordine ben preciso, ciascuno di lunghezza definita, senza tag di apertura o chiusura. b - I campi opzionali possono essere inseriti allinterno del messaggio SIP2 in un ordine qualunque, purch risiedano tutti nella sottostringa compresa tra i campi obbligatori e i campi di error detection. Ogni campo opzionale ha il suo proprio tag di apertura, definito da due caratteri maiuscoli, e un carattere di chiusura, che invece comune a tutti gli altri campi, generalmente pipe ( | ). c - I campi di error detection sono solo due. Sono provvisti di un tag di apertura costituito da due caratteri maiuscoli (AY e AZ) ma, al contrarion dei campi opzionali, non possiedono tag di chiusura.

Ogni messaggio ha i suoi propri campi. Vuol dire che messaggi differenti avranno non solo contenuti differenti ma anche una struttura differente, sempre per definita dalle tre sottostringhe di cui sopra. Il tipo di messaggio definito dal suo codice identificativo situato in testa allo stesso. Se il codice un numero dispari il messaggio sar di tipo request, se al contrario un numero pari il messaggio sar di tipo response. SIP2 lavora a coppie di messaggi: lutente invia una richiesta (request) e il server risponde con il messaggio (response) corrispondente.

1 - Formattazione
file di esempio: example_01.php Il modulo provvede alla creazione di messaggi SIP2 attraverso il metodo sip2request::formatMSG( $msg_code, $fields_values = array() ). Il parametro $msg_code definir il codice identificativo del messaggio, mentre il parametro opzionale $fields_values contiene i valori dei campi del messaggio. possibile, configurando adeguatamente il modulo dal file ./config.default.php, definire a priori il valore di alcuni dei campi interessati, rendendo quindi obsoleto linserimento di dati nel parametro $fields_values. Questo sistema pu essere usato in modo parziale o totale, a seconda delle necessit e del tipo di messaggio. Se per esempio dobbiamo usare spesso un messaggio 99 per ricevere lo stato del server SIP2 a cui siamo collegati, non abbiamo particolari necessit di modificare i valori da passare alla funzione per la composizione del messaggio di volta in volta, ci baster configurare i campi che lo compongono al momento dellinstallazione, permettendoci di ignorare il parametro $fields_values. Al contrario, tutti i valori inseriti in $fields_values, andranno a rimpiazzare eventuali valori predefiniti. Nel file desempio viene formattato un messaggio 99 usando tre tecniche differenti:
a - formattazione di un messaggio SIP2 usando i soli valori predefiniti. b - formattazione di un messaggio SIP2 sovrascrivendo tutti i valori predefiniti. c - formattazione di un messaggio SIP2 effettuando una sostituzione parziale dei valori predefiniti.

Nota: I valori inseriti in fase di costruzione del messaggio hanno la precedenza su quelli definiti in fase di configurazione e rimarranno valididi solo per quel singolo messaggio. Tutti quei valori che non vengono inseriti in fase di costruzione del messaggio verranno cercati nel file di configurazione. Se questo valore appartiene ad un campo obbligatorio e non presente nel file di configurazione, il messaggio non potr essere formattato correttamente.

2 - Scomposizione
file di esempio: example_02.php Prima di poter interpretare un messaggio ricevuto dal server SIP2, necessario scomporlo nei campi che lo compongono. Il metodo sip2response::splitMSG( $string ), in grado di generare un array associativo dei campi che costituiscono il messaggio $string. Larray cos ottenuto conterr per ciascun nome dei campi che costituiscono il messaggio $string il suo proprio valore. Lesempio illustra la scomposizione di due messaggi differenti e lacquisizione degli array corrispondenti e due modi distinti. Il file desempio effettua la scomposizione di una data stringa, stampando a schermo larray associativo risultante.

3 - Interpretazione
file di esempio: example_03.php SIP2PHP da la possibilit di restituire delle interpretazioni personalizzabili dei messaggi di risposta inviati dal server SIP2. Il metodo sip2response::parse_fields() accetta come parametro un array associativo prodotto dalla funzione sip2response::splitMSG() e genera un nuovo array associativo. Una volta scomposto un messaggio SIP2 nei valori dei campi che lo compongono, il metodo sip2response::parse_fields( $response_fields ) genera un array associativo contenente, per ogni campo contenuto nel messaggio, uninterpretazione di quel valore. Possiamo per chiarezza definire simbolicamente 4 tipi di interpretazioni dei valori di un messaggio SIP2:
a - iterpretazioni predefinite. b - Interpretazioni bianche. c - interpretazioni numeriche. d - interpretazioni di date. a - Campi la cui interpretazione una stringa di testo decisa a priori in fase di configurazione. Il file config.default.php contiene tutti i valori predefiniti di questi campi. b - Campi che contengono gi un messaggio esteso e comprensibile e pertanto non interpretabile ulteriormente. Tali stringhe vengono restituite cos come sono. c - Campi la cui interpretazione di ordine numerico e non configurabile, come ad esempio il campo charged_items_count. d - Campi contenenti date formattate secondo SIP2 e che possono essere interpretate selezionando un formato e un paese (Locale) nel file di configurazione.

Esistono per dei campi la cui interpretazione pi complessa, come ad esempio i campi BX e patron_status, che il programma interpreta come array, piuttosto che una stringhe di testo. Il singolo valore di questi campi racchiude una certa quantit di dati, che vanno a loro volta interpretati. Questo programma si limita a scomporre quest campi speciali in array e ad assegnare a ciascuno dei suoi indici, linterpretazione corrispondente. Il file example_03.php contiene un esempio di scomposizione e interpretazione di un messaggio SIP2.

Nota: Per avere unidea pi chiara dellinterpretazione dei messaggi SIP2, riferirsi ai manuali 3M.

4 - Invio e ricezione
file di esempio: example_04.php Il modulo SIP2PHP permette di inviare e ricevere messaggi SIP2 via socket. Una volta definito lindirizzo del server SIP2, la funzione sip2client::send_and_retrive(), permette di inviare un messaggio e di restituire la stringa trasmessa dal server. In questo file desempio, viene eseguito uno scambio di pacchetti socket con il server SIP2, inviando un messaggio gi correttamente formattato e ricevendone risposta.

Nota: Per eseguire questo script necessario aver configurato correttamente il software, avendo prestato particolare attenzione ad inserire un valido indirizzo di server SIP2.

5 - Transazione completa, parte 1

file di esempio: example_05.php Gli esempi illustrati nei paragrafi precedenti costituiscono i singoli passaggi per effettuare una transazione SIP2 completa e per ricevere uninterpretazione del suo esito. Il file desempio raccoglie questi passaggi in un unico script. Lo script chiama in successione le seguenti funzioni:
sip2request::formatMSG(). sip2socket::send_and_retrive(). sip2response::splitMSG(). sip2request::parse_fields().

Nota: Per eseguire questo script necessario aver configurato correttamente il software, avendo prestato particolare attenzione ad inserire un valido indirizzo di server SIP2.

6 - Transazione completa, parte 2

file di esempio: example_06.php Come spiegato nei paragrafi precedenti, SIP2PHP permette di effettuare transazioni SIP2 complete, chiamando in successione le funzioni precedentemente illustrate. La funzione sip2php::transaction() automatizza questoperazione dando la possibilit di effettuare con una sola chiamata, una transazione completa. Il file desempio produce una transazione SIP2 e linterpretazione del suo esito adoperando questa singola funzione.

Nota: sip2php::transaction() restituisce un valore numerico che ne descrive lesito. Linterpretazione del messaggio inviato dal server SIP2, come qualunque altro dato, va raccolto effettuando una chiamata alla variabile corrispondente.

SIP2PHP 1.0 2007-8 - Caspur, Dip. Di Fisica Universit di Roma Sapienza, Polo SBN RMS