Driver SL per Windows 95 / 98

Manuale d'uso

Progetto di riferimento: Driver SL per Windows 95 / 98 Revisione documento: 1.0 Data revisione: 14/05/99 Redatto da: LV Riferimenti: Manuale standard SL vers. 2.0 e add-on successivi File: SLW32_UT.DOC

Legenda.......................................................................................................................................................................2

Scopo ed Obiettivi................................................................................................................................3
Introduzione.................................................................................................................................................. 3

Requisiti dell'utilizzatore.....................................................................................................................3 Configurazione del sistema.................................................................................................................3 Introduzione all'uso Cosa il Driver SL per Windows 95 / 98 ? .....................................................3
Cosa una Dynamic Link Library ? .......................................................................................................... 4 Differenze tra librerie dinamiche e statiche in Windows.......................................................................... 4 Vantaggi nell'utilizzo di una DLL............................................................................................................... 5

Schema a blocchi del Driver SL per Windows 95 / 98......................................................................6

Esempio di gestione di due Ecr con doppia istanza alla DLL .................................................................. 6 Come utilizzare il driver SL 95 / 98 ............................................................................................................ 6 La struttura dell'applicativo........................................................................................................................ 7

Funzioni disponibili nel driver Sarema Language per Windows 95 ................................................7

SLW32Close.................................................................................................................................................. 7 SLW32GetVersion........................................................................................................................................ 8 SLW32InitCom............................................................................................................................................. 9 SLW32Open................................................................................................................................................ 10 SLW32Read ................................................................................................................................................ 11 SLW32Write ............................................................................................................................................... 12

Legenda SL: ECR: PC: VC++: VB: DLL: Sarema Language Registratore di cassa Personal Computer Visual C++ (vers. 5.0 o successive) Visual Basic (vers. 5.0 o successive) Dynamic Link Libraries

Scopo ed Obiettivi
Introduzione

Il Driver SL per Windows 95 / 98 un insieme di moduli software che interagiscono con il Sistema Operativo Microsoft Windows versionI 95 e 98, che permette di gestire il colloquio attraverso la linea seriale RS-232 con un registratore di cassa aderente allo standard Sarema Language tramite un programma applicativo opportunamente predisposto. Questo manuale descrive la struttura dei moduli software utilizzati e fornisce informazioni dettagliate sul loro funzionamento e sulla loro interfaccia verso un applicativo. Nei successivi capitoli si forniscono le principali informazioni necessarie alla creazione di applicativi che utilizzano il Driver SL per Windows 95 / 98.

Requisiti dell'utilizzatore
Questo manuale rivolto ad un programmatore che desidera scrivere una nuova applicazione o modificarne una esistente, per gestire la comunicazione con un registratore di cassa aderente allo standard Sarema Language in ambiente Windows 95 e 98. Per utilizzare il Driver SL per Windows 95 richiesta una conoscenza approfondita di uno qualsiasi degli ambienti di sviluppo per applicativi in ambiente Windows (Visual C++, Visual Basic, Turbo Pascal per Windows, Borland C++ o altri) e delle caratteristiche di base delle Dynamic-Link-Libraries.

Configurazione del sistema

Il Driver SL per Windows necessita di un personal computer dotato di processore 486 o superiore, almeno 2 MBytes di memoria RAM (sono consigliati 4 MBytes) e almeno 1 Mbyte di spazio libero su disco. Nel PC deve essere il sistema operativo Windows 95 o 98, entrambi della Microsoft.

Introduzione all'uso
Cosa il Driver SL per Windows 95 / 98 ?

Il Driver SL per Windows 95 / 98 costituito da due DLL denominate W32SLM1.dll (principale) e W32SLS1.dll (secondaria). Questultima, responsabile della gestione del protocollo a basso livello con lEcr, risulta invisibile allapplicativo e viene caricata automaticamente dalla prima DLL dopo che questa a sua volta stata caricata dallapplicativo. La DLL principale pu essere usata per aprire o chiudere la comunicazione con un registratore di cassa con protocollo compatibile Sarema Language, configurare il tipo di comunicazione, leggere e scrivere dati tramite lesportazione di una serie di funzioni descritte nel seguito.

Cosa una Dynamic Link Library ? Nella programmazione con linguaggi ad alto livello come C, Pascal, o Fortran, un file sorgente deve essere compilato e poi collegato a varie librerie per creare un file eseguibile. Queste librerie contengono delle funzioni precompilate che vengono invocate dal file sorgente per portare a temine operazioni di carattere generale, come ad esempio allocare memoria o calcolare la radice quadrata di un numero. Quando queste funzioni di libreria sono linkate ad una applicazione, diventano parte integrante e permanente del file eseguibile. Tutte le chiamate alle funzioni di libreria sono risolte al momento del collegamento (linking), da cui il nome di collegamento statico. Il collegamento dinamico provvede invece a collegare l'applicazione alle librerie al momento del caricamento in memoria o dell'esecuzione (a run-time). Le librerie risiedono in un diverso file eseguibile e non vengono copiate all'interno del file eseguibile dell'applicazione come per il collegamento statico. Queste librerie vengono chiamate Dynamic Link Libraries (DLLs) per enfatizzare il fatto che sono collegate all'applicazione in modo dinamico ogni volta che questa viene eseguita e non a priori al momento del collegamento. Quando una applicazione usa una DLL, il sistema operativo la carica in memoria, risolve i riferimenti per le funzioni contenute e scarica la DLL quando non pi necessaria. Differenze tra librerie dinamiche e statiche in Windows Le differenze principali tra le DLL e le librerie statiche sono le seguenti:

Le librerie statiche risiedono in un file .LIB, che una collezione di moduli oggetto, mentre le DLL risiedono in un file eseguibile che viene caricato in memoria dal sistema operativo Windows quando necessario Ogni applicazione che usa una libreria statica ne contiene una propria copia. Windows invece permette a pi applicazione di condividere la stessa DLL. Le librerie statiche possono contenere solo codice e dati, mentre le DLL possono contenere anche risorse come bitmap, icone e cursori.

Le librerie statiche devono usare il segmento dati dell'applicazione mentre le DLL possono avere un proprio segmento dati.

Vantaggi nell'utilizzo di una DLL Il vantaggi pi evidenti che offre una DLL rispetto ad una libreria statica sono la modularit e la possibilit di diminuire la dimensione del codice eseguibile. Per modularit si intende la possibilit di dividere il software in parti funzionali diverse. Le librerie statiche consentono la modularizzazione a livello di funzione, permettendo di incapsulare il codice in routines e subroutines. Le DLL lo fanno invece a livello di sistema, consentendo di isolare intere applicazioni da cambiamenti esterni. Poich una DLL viene compilata e linkata indipendentemente dall'applicazione che la utilizzer, pu venire modificata senza richiedere alcuna modifica alle applicazioni che la utilizzano. Un esempio dei benefici che si possono ottenere con le DLL di rendere indipendente un'applicazione che collega un registratore di cassa dall'implementazione di una nuova versione del firmware. Aggiornando la DLL, l'applicazione pu implementare le nuove funzionalit senza nessuna modifica. Ulteriori e pi specifiche informazioni sulle caratteristiche di una Dynamic Link Library si trovano nel manuale Guide to Programming - Microsoft Windows Software Development Kit, capitolo 20.

Schema a blocchi del Driver SL per Windows 95 / 98

Esempio di gestione di due Ecr con doppia istanza alla DLL
ECR 1 ECR 2

w32sls1.dll

w32sls1.dll

SL

SL

w32slm1.dll

w32slm1.dll

Programma applicativo

Come utilizzare il driver SL 95 / 98 In primo luogo il programma applicativo dovr eseguire il caricamento dinamico della DLL principale (Es. LoadLibrary per VC++, o Declare per VB). Dopo essere stato caricato in memoria, il Driver SL per Win 95 / 98, tramite le proprie funzioni esportate, permette la gestione completa del protocollo a basso livello con un registratore di cassa compatibile SL. Attivando le funzioni di lettura dei dati provenienti da Ecr (vedi funzione di Read), il programma applicativo in grado di ricevere ogni messaggio trasmesso dallEcr stesso (gi tradotto in formato SL) e di gestire la sessione di protocollo con una trasmissione di dati o, qualora non abbia nulla da trasmettere, chiudendo automaticamente la sessione di protocollo in corso tornando semplicemente in fase di lettura dati. La DLL comunicazione che gestisce il colloquio fisico con lEcr, garantisce il mantenimento della sincronizzazione con lEcr tramite trasmissione automatica di un carattere di Wait che pone lEcr stesso in stato di attesa di una risposta dallHost per almeno 8 secondi.

L'applicativo pu inviare un pacchetto dati al registratore di cassa usando le funzioni contenute nel Modulo SL che lo traducono e lo passano al Device Driver SL. Quest'ultimo si preoccupa di controllare l'effettiva e corretta trasmissione al registratore di cassa. Attenzione: per una gestione completa e affidabile della interattivit con lEcr, necessario che il programma applicativo attivi un proprio processo (ad. Es un timer in VB, un timer o un thread dedicato in VC++) che esegua continuamente operazioni di lettura tramite la funzione SLW32Read. Questo permette allapplicativo la gestione di ogni sessione di protocollo con lEcr e la relativa ricezione dei messaggi provenienti dallEcr stesso. Lapplicativo potr di volta in volta decidere quale gestione attivare dei messaggi ricevuti. Come gi sopra specificato, dopo una ricezione, il ritorno del programma in fase di Read, chiude la singola sessione di protocollo con lEcr attivando la conferma automatica della transazione precedente. Nota: per ulteriori informazioni relative al principio di funzionamento del protocollo Sarema Language fare riferimento al manuale SL rel. 2.0 e successive integrazioni. La struttura dell'applicativo L'applicativo che vuole instaurare una comunicazione con un registratore di cassa, dopo avere eventualmente settato i parametri di comunicazione con lEcr tramite la funzione SLW32InitCom (Nota: il protocollo SL fissa i parametri ai valori 8 (dati) , No parity, 1 stop bit, valori non modificabili e gi attivi di default sul driver; per cui tale funzione pu risultare inutile o eventualmente essere usata solo per riprogrammare il baud rate), dovr eseguire la funzione SLW32Open per aprire la comunicazione con lEcr. Attenzione: la presente versione di driver SL per W95 non permette di filtrare i sincronismi, opzione invece attiva sulla versione per Windows 3.1.

Funzioni disponibili nel driver Sarema Language per Windows 95

SLW32Close SHORT SLW32Close(nPort) La funzione SLW32Close chiude la comunicazione con un registratore di cassa. nPort: Specifica la porta di comunicazione che si desidera chiudere.

Parametri

Valore di ritorno

Il valore di ritorno zero se l'operazione stata eseguita correttamente, altrimenti un numero negativo. I possibili valori possono essere: DRV_OK: Operazione eseguita correttamente DRV_BADID: Identificativo della porta non valido. DRV_MEMORY: Problemi di memoria. DRV_NOPEN Porta gi aperta

Commenti Esempio

La chiusura fallisce se si tenta di chiudere una comunicazione che non stata mai aperta. L'esempio seguente usa la funzione SLW32Close per chiudere la comunicazione con un registratore di cassa collegato su COM1: fRetVal = SLW32Close (1);

Riferimenti

SLW32Open, SLW32InitCom

SLW32GetVersion SHORT SLW32GetVersion(SHORT TYPE, LPSTR lpOutString) La funzione SLW32GetVersion ritorna una stringa contenente la revisione della Dll SL in uso e/o la revisione della Dll di comunicazione

Parametri

Type: [0] : SL DLL release, [1] Communication DLL release lpOutString ptr alla stringa contenente la versione

Valore di ritorno Struttura stringa release

Il valore di ritorno specifica se loperazione di lettura ha avuto successo [0] = OK / [-1] = not OK SL-Win32 - rel. 1.01 SLComm-Win32 - rel. 1.00

Esempio

L'esempio seguente usa la funzione SLW32GetVersion per mostrare a video la versione del Driver SL: char szBuffer[80]; short sResult; sResult = SLW32GetVersion (0, szBuffer) ; sResult = SLW32GetVersion (1, szBuffer) ;

Riferimenti

Nessuno

SLW32InitCom

SHORT SLW32InitCom (SHORT nPort, SHORT Baud, SHORT Parity, SHORT DataLen, SHORT StopBit)

La funzione SLW32InitCom imposta i parametri di comunicazione per la porta specificata.

Parametri

nPort: numero di porta [1-4] Baud: Baud rate [1200-9600] Parity: parit [N : nessuna parit per protocollo Sarema] DataLen: Data Length [fisso a 8 per protocollo Sarema] StopBit: Bit di stop [fisso a 1 per protocollo Sarema] Il valore di ritorno zero se l'operazione stata eseguita correttamente; altrimenti un numero negativo. I possibili valori possono essere: DRV_OK: Operazione eseguita correttamente DRV_BADID: Identificativo della porta non valido. DRV_MEMORY: Problemi di memoria. DRV_NOPEN: Porta non ancora aperta. DRV_BAUDRATE: Baud Rate non valido. DRV_BYTESIZE: Byte Size non valido. DRV_PARITY: Parity non valida. DRV_STOPBITS: Valore Stop Bits non valido. DRV_ERROR: Errore generico.

Valore di ritorno

Esempio

L'esempio seguente usa la funzione SLW32InitCom per configurare il tipo di comunicazione con un registratore di cassa collegato su COM1 a 9600 Baud, no parit, 8 bit di dati e 1 bit di stop istruendo inoltre il Driver SL a filtrare i sincronismi. fRetVal = SLW32InitCom (1,9600,0x4e,8,1);

Riferimenti

SLW32Close, SLW32Open

SLW32Open SHORT SLW32Open(nPort) La funzione SLW32Open apre la comunicazione con un registratore di cassa.

Parametri

nPort : Specifica la porta di comunicazione che si desidera aprire. Il valore di ritorno zero se l'operazione stata eseguita correttamente; altrimenti un numero negativo. I possibili valori possono essere: DRV_OK: Operazione eseguita correttamente DRV_BADID: Identificativo della porta non valido. DRV_MEMORY: Problemi di memoria. DRV_OKOPEN: Porta gi aperta L'apertura della porta potrebbe fallire se vengono riscontrati errori hardware o se non c' memoria sufficiente per allocare le risorse necessarie al corretto funzionamento del driver. L'esempio seguente usa la funzione SLW32Open per aprire la comunicazione con un registratore di cassa collegato su COM1: fRetVal = SLW32Open (1); if (fRetVal < 0) MessageBox("Errore durante l'apertura di COM1");

Valore di ritorno

Commenti

Esempio

Riferimenti

SLW32Close SLW32InitCom

SLW32Read SHORT SLW32Read (nPort, lpOutString) La funzione SLW32Read effettua una operazione di lettura dati sul buffer di ricezione su cui vengono memorizzati i dati trasmessi dal registratore di cassa. nPort: Specifica la porta di comunicazione su cui si desidera leggere. lpOutString: indirizzo del buffer di ricezione sul quale si intendono memorizzare i dati ricevuti dallEcr La funzione SLW32Read pu anche essere usata per inviare allEcr una conferma implicita in seguito alla ricezione di un pacchetto dati. Infatti se viene invocata quando non ci sono messaggi da gestire e il registratore di cassa sta attendendo una risposta da parte del personal computer, la SLW32Read invia un carattere ACK e chiude la singola sessione di protocollo. Il valore di ritorno pu assumere i seguenti significati: DRV_OK: DRV_BADID: DRV_MEMORY: DRV_ERROR: Operazione eseguita correttamente Identificativo della porta non valido. Problemi di memoria. Errore generico

Parametri

Commenti

Valore di ritorno

Nel campo codice possono essere specificati i seguenti valori: DRV_RXDOK: Pacchetto dati ricevuto correttamente. DRV_NORXD: Nessun pacchetti dati ricevuto dal registratore di cassa. DRV_NOSYNC: Pacchetto dati ricevuto, ma shorterattivit scaduta, DRV_BUFF_CORTO: Buffer di comunicazione di dimensione insufficiente a contenere il pacchetto dati. DRV_BUFF_OVERRUN: Buffer di ricezione pieno.

Esempio

L'esempio seguente usa la funzione SLW32Read per leggere il pacchetto dati ricevuto dal registratore di cassa collegato su COM1: fRetVal = SLW32Read (1, lpComBuff); if (fRetVal == DRV_OK) VerificaMessaggio (1, lpComBuff); SLW32Open, SLW32Write

Riferimenti

SLW32Write SHORT SLW32Write (nPort, lpInpString) La funzione SLW32Write invia un pacchetto dati ad un registratore di cassa. nPort: specifica la porta di comunicazione su cui si desidera trasmettere. lpInpString: prt alla stringa SL da trasmettere allECR Il valore di ritorno pu assumere i seguenti significati: DRV_OK: DRV_BADID: Operazione eseguita correttamente Identificativo della porta non valido.

Parametri

Valore di ritorno

DRV_MEMORY: Problemi di memoria. DRV_ERROR: Errore generico. DRV_TXDERROR Dati trasmessi fuori sincronismo Commenti Il protocollo SL permette la trasmissione di un dato allEcr solo successivamente ad una lettura con successo (Ecr ha trasmesso un messaggio e si trova in stato di Wait); pertanto qualsiasi tentativo di scrittura che non rispetti tale sequenza generer un messaggio di errore del tipo DRV_TXDERROR senza peraltro generare alcun effetto sullEcr

Esempio

L'esempio seguente usa la funzione SLW32Write per inviare il comando di vendita al reparto 1 di .1000 alla ricezione di un sincronismo da Ecr (porta 1). fRetVal = SLW32Read (1, lpComBuff); if ((fRetVal == DRV_OK) && (pDest = strstr(lpComBuff,SYN)) != NULL) { strcpy(ComBuff, "SALE,N1,P1000;"); fRetval = SLW32Write (1, ComBuff); if (fRetval == DRV_OK) {..}

} Riferimenti

SLW32Open, SLW32Read