Driver SL per Windows 95 / 98 Manuale d'uso

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). Quest ultima, responsabile della gestione del protocollo a basso livello con l Ecr, risulta invisibile all applicativo e viene caricata automaticamente dalla prima DLL dopo che questa a sua volta è stata caricata dall applicativo. 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 l esportazione 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 dall Ecr 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 l Ecr, garantisce il mantenimento della sincronizzazione con l Ecr tramite trasmissione automatica di un carattere di Wait che pone l Ecr stesso in stato di attesa di una risposta dall Host 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 l Ecr, è 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 all applicativo la gestione di ogni sessione di protocollo con l Ecr e la relativa ricezione dei messaggi provenienti dall Ecr stesso. L applicativo 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 l Ecr 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 l Ecr 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 l Ecr. 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. Parametri nport: Specifica la porta di comunicazione che si desidera chiudere.

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 l operazione 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] 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 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.

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. 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_OKOPEN: Porta già aperta Commenti 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. Esempio 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");

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. Parametri Commenti Valore di ritorno 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 dall Ecr La funzione SLW32Read può anche essere usata per inviare all Ecr 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 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); Riferimenti SLW32Open, SLW32Write SLW32Write SHORT SLW32Write (nport, lpinpstring) La funzione SLW32Write invia un pacchetto dati ad un registratore di cassa. Parametri nport: specifica la porta di comunicazione su cui si desidera trasmettere. lpinpstring: prt alla stringa SL da trasmettere all ECR Valore di ritorno Il valore di ritorno può assumere i seguenti significati: DRV_OK: DRV_BADID: Operazione eseguita correttamente Identificativo della porta non valido. 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 all Ecr 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 sull Ecr

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