Manuale per la programmazione Tivoli Service Desk 6.0 Developer's Toolkit Script

Capitolo 7: il sistema di moduli

Ritorna all'Indice analitico


Introduzione

Definizione

TSD Script offre un sistema moduli che viene utilizzato per creare le finestre da un file di descrizione (risorsa).

Un modulo è una finestra contenente alcuni tipi di moduli di immissione dati. In un ambiente GUI, il modulo è il primo mezzo di interazione tra l'utente e l'applicazione. Uno sviluppatore posiziona i controlli sul modulo vuoto selezionandoli da una barra degli strumenti. I controlli dei moduli comprendono:

Controlli del modulo

Un controllo del modulo è un elemento che viene utilizzato per ottenere informazioni dall'utente o per fornirle all'utente. Ad esempio, un modulo di immissione dati generalmente contiene uno o più controlli casella di testo, un pulsante OK e un pulsante Annulla. Progettazione d'interfaccia Developer's Toolkit può essere utilizzato per aggiungere i controlli a un modulo (consultare il Manuale per la progettazione d'interfaccia Tivoli Service Desk 6.0 Developer's Toolkit per ulteriori informazioni).

Il seguente elenco comprende tutti i controlli del modulo supportati dal TSD Script.

Nome del controllo Descrizione
Sottomodulo Controllo complesso che contiene diversi altri controlli.
Casella di testo Area rettangolare che consente all'utente di immettere una singola riga di informazioni. Se l'utente immette un testo più lungo che può essere contenuto su una singola riga, la casella scorre automaticamente.
Casella di testo a più righe Area rettangolare utilizzata per immettere più righe di testo. Facoltativamente, il testo può essere creato in modo da consentire l'unione della parola all'interno della casella.
Casella di elenco Casella rettangolare che contiene un elenco delle scelte possibili. Gli utenti non possono immettere una selezione in una casella di elenco.
Casella combinata Casella di testo con una casella di elenco collegata. L'utente può immettere un valore nella casella di testo oppure selezionare un valore nell'elenco a discesa. Il valore selezionato appare nella caselle di testo e la casella di elenco scompare.
Albero Controllo che visualizza i dati in ordine gerarchico.
Pulsanti Opzioni Il pulsante utilizzato per selezionare una oppure un'insieme di scelte che si escludono a vicenda. Gli utenti selezionano un pulsante; tale pulsante viene quindi riempito.
Casella di spunta Caselle quadrate le cui opzioni possono essere selezionate o eliminate per attivare o disattivare un'opzione. E' possibile selezionare più di una casella di spunta alla volta.
Dispositivo di scorrimento Una barra che si sposta in modo interattivo.
Pulsante Pulsante rettangolare che avvia un'azione.
Testo Campo che visualizza il testo. Gli utenti non possono modificare il testo.
Orologio Un orologio per l'ora-del-giorno in funzione oppure un contatore del tempo trascorso.
Tabella Dati strutturati in righe e colonne.
Ipertesto Area che visualizza il testo in un formato hypertext.
Casella di gruppo Una cornice rettangolare che raggruppa diversi controlli per significato o funzionalità.
Immagine Campo in cui viene visualizzata un'immagine da un file.

File del modulo

I moduli vengono conservati come risorse di applicazione separate. Il Developer's Toolkit consente di creare una raccolta di specifiche di modulo e di memorizzarle in file con estensione .df. Come per i file .kb (knowledgebase), esiste un modulo origine e un modulo oggetto per tali specifiche. Un file con estensione .df abilita i menu, le barre degli strumenti e le stringhe.

Il Generatore d'interfaccia è un programma TSD Script che prende un file origine .df e crea un file oggetto .dfc. I file .dfc vengono caricati e visualizzati dal Developer's Toolkit al momento dell'esecuzione.

Codice modulo di esempio

Il seguente esempio di un frammento di codice TSD Script utilizza un modulo.

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
      END; 
VARIABLES 
      employee: EmployeeRecord; 
    ACTIONS 
  IF DlgBox($Desktop,'EMPLOYEE.DFC[ADDFORM]',
            $NullHandler,employee) > 0 THEN 
        SQLInsert('EMPLOYEES',employee); 
      END; 

Nell'esempio, è stato dichiarato un nuovo tipo di EmployeeRecord nella sezione tipi. Nella sezione dedicata alle variabili, esiste inoltre una variabile di questo tipo. Nomi del campo del record identici ai nomi dei controlli del modulo.

L'istruzione DlgBox nella sezione dedicata alle azioni consente di eseguire le seguenti operazioni:

Generalmente i moduli contengono anche i pulsanti OK e Annulla.

Argomenti dell'istruzione DlgBox

L'istruzione DlgBox considera quattro argomenti:

Titolo dell'argomento Descrizione
Finestra padre L'handle per la finestra che crea una finestra padre per il nuovo modulo.
File modulo Il nome di un file di specifica del modulo compilato. Se il file contiene più di una specifica di modulo, il nome
del modulo desiderato deve essere racchiuso tra parentesi quadre che seguono il nome del file.
Handler degli eventi Come le finestre generiche già trattate in precedenza, tutti i moduli hanno un handler degli eventi ad essi associato.

A volte, è possibile che l'utente desideri che l'handler esegua delle funzioni di default per ogni evento. In questi casi, è possibile
specificare $NullHandler. In questo caso, $NullHandler consente all'utente di spostarsi da controllo a controllo
e di immettere i valori nel modulo.

Quando l'utente seleziona un pulsnate con Accetta proprietà, TSD Script copia automaticamente il contenuto dei controlli del modulo nei
campi corrispondenti nella variabile risultato.

Variabile risultato Una variabile del record i cui campi corrispondono ai controlli nel modulo.

Quando un utente esce da un modulo premendo un pulsante con la proprietà Accetta, il contenuto di ogni controllo sul modulo viene copiato
nei campi corrispondenti della variabile record. La variabile record può essere quindi scritta su un database, visualizzata
in una finestra, o qualunque cosa sia appropriata per l'applicazione.

Esempio DlgBox

Si prenda in considerazione un altro esempio:

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
      END; 
VARIABLES 
      employee: EmployeeRecord; 
    ACTIONS 
  SQLSelectInto('SELECT * FROM EMPLOYEES WHERE 
              SSN=305-33-4111',employee); 
  IF DlgBox($Desktop,'EMPLOYEE.DFC[EDITFORM]',
            $NullHandler{employee},employee) >> 0 THEN 
    SQLUpdate('EMPLOYEES','WHERE SSN=''' & 
            employee.snn & '''',employee); 
      END; 

Questo esempio mostra il codice che:

Sono state apportate due modifiche a questa istruzione DlgBox:

In questo esempio, l'utente visualizza le informazioni richiamate dalla tabella EMPLOYEES nel modulo e può spostarsi in un qualunque modulo e modificare qualsiasi informazione.

Handler degli eventi modulo

Per gestire le caratteristiche avanzate, come ad esempio la visualizzazione di una foto del dipendente quando l'utente sceglie un pulsante o la convalida del formato di un numero di previdenza sociale, è necessario utilizzare un handler degli eventi. Per far ciò è necessario creare gli handler degli eventi modulo.

Esempio di handler degli eventi

Questa sezione introduce un modulo con un handler degli eventi. L'esempio rappresenta un intero file .kb (knowledgebase) definito Employees che implementa una singola funzione pubblica denominata AddEmployee. Il corpo AddEmployee è simile agli esempi precedenti, solo che invece di utilizzare $NullHandler, fa riferimento all'handler degli eventi denominato EmployeeEvent.

KNOWLEDGEBASE Employees; 
  USES 
  Globals; 
  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
      END; 
    ROUTINES 
    FUNCTION AddEmployee: BOOLEAN; 
PRIVATE 
    ROUTINES 
    EVENT EmployeeEvent(REF employee: 
                        EmployeeRecord) IS 
    ROUTINES 
      FUNCTION ValidSSN(VAL ssn: STRING): BOOLEAN IS 
VARIABLES 
  i: INTEGER; 
    ACTIONS 
        IF StrLength(ssn) <> 11 THEN 
        EXIT(FALSE); 
      END; 
        FOR i:=1 TO 11 DO 
          IF (i = 4 OR i = 7) AND (ssn[i] <> '-') THEN 
        EXIT(FALSE); 
          ELSIF StrPos('0123456789',ssn[i]) = 0 THEN 
        EXIT(FALSE); 
      END; 
      END; 
        EXIT(TRUE); 
      END (* Valid SSN *); 
        ACTIONS 
WHEN $Event IS $MsgSelect THEN 
        WHEN $FieldName IS 'SSN' THEN 
          IF NOT ValidSSN(employee.ssn) THEN 
            Exit(0); 
      END; 
        ELSWHEN 'PICTURE_BUTTON' THEN 
          ShowPicture(employee.last_name & '.BMP'); 
      END; 
      END; 
    END (* Employee Event *); 
    FUNCTION AddEmployee: BOOLEAN IS 
VARIABLES 
      employee: EmployeeRecord; 
    ACTIONS 
      IF DlgBox(mainWindow, 'EMPLOYEE.DFC[ADDFORM]',
                EmployeeEvent{employee},employee) > 0 THEN 
        SQLInsert('EMPLOYEES',employee); 
        EXIT(TRUE); 
      ELSE 
        EXIT(FALSE); 
      END; 
    END (* Add Employee *); 

EmployeeEvent è un handler degli eventi che prende un singolo parametro passato per riferimento dello stesso tipo della variabile di ritorno passata in DlgBox.

L'handler degli eventi testa solo un evento, $MsgSelect, e viene creato ogni volta che il modulo sta per spostare il cursore al di fuori del controllo corrente.

Se l'utente immette un valore in un controllo di testo e preme il tasto TAB, viene creato un evento $MsgSelect. Il nome del controllo che l'utente sta per lasciare si presenta con questo evento in un parametro "invisibile" denominato $FieldName.

L'esempio successivo assomiglia più al corpo di EmployeeEvent.

WHEN $Event IS $MsgSelect THEN 
        WHEN $FieldName IS 'SSN' THEN 
          IF NOT ValidSSN(employee.ssn) THEN 
            Exit(0); 
      END; 
        ELSWHEN 'PICTURE_BUTTON' THEN 
          ShowPicture(employee.last_name & '.BMP'); 
      END; 
      END; 

Questo esempio illustra quanto segue:

Il risultato di default è "1," che indica l'esito positivo. Tuttavia, si verificano casi in cui è necessario restituire un valore differente.

Evento $MsgSelect

Alcuni eventi creati da TSD Script vengono automaticamente rifiutati quando l'handler degli eventi termina con un valore 0. $MsgSelect è uno di questi.

Se EmployeeEvent scopre che è stato fornito un numero di previdenza sociale non valido durante l'elaborazione dell'evento $MsgSelect per il campo SSN, questo termina con un valore 0.

Tutto ciò viene definito come rifiuto dell'evento. Il risultato di questo rifiuto è doppio.

Creazione di un evento $MsgSelect

Generalmente, l'evento $MsgSelect mette al corrente l'utente del fatto che qualcosa, nel modulo, è cambiato. $MsgSelect può essere creato in uno di questi tre modi:

Nota: $MsgSelect viene creato solo quando un nuovo valore differisce dal precedente.

Nota: Premere INVIO equivale a scegliere il pulsante comando di default, se ne è stato definito uno. Questo crea un evento $MsgAccept. Qualora non esistesse alcun pulsante comando di default, viene creato un evento $MsgSelect.

Quando l'handler degli eventi riceve l'evento $MsgSelect, i dati di istanza della finestra (a cui fa riferimento l'handler degli eventi con il proprio argomento record) vengono aggiornati per riflettere le modifiche. Ad esempio, quando un utente immette un valore nella casella di testo SSN e preme il tasto TAB, il valore viene copiato nel campo SSN della variabile di istanza della finestre e viene creato un evento $MsgSelect. Il valore del campo precedente è disponibile nel primo parametro degli eventi non denominato.

Il valore del controllo non viene definito fino a quando non si completa il messaggio Select; tuttavia il valore del controllo non può essere interrogato.

Altri eventi modulo

I moduli possono creare un numero di eventi aggiuntivi, compresi:

Eventi moduli Descrizione
$MsgInitialize Versione speciale di $MsgSelect che si verifica solo durante la fase di creazione di un modulo.
$MsgCreate Ricevuto prima della visualizzazione del modulo. Questo è il momento adatto per eseguire operazioni come l'aggiunta
dell'elenco di possibili scelte ad una casella di elenco e così via.
$MsgDestroy Ricevuto prima della chiusura di un modulo.
$MsgAccept Ricevuto quando l'utente accetta un modulo, generalmente premendo INVIO o selezionando OK.
$MsgCancel Ricevuto quando l'utente annulla un modulo, generalmente premendo ESC o selezionando ANNULLA.
$MsgEnterField Ricevuto quando il cursore sta per specificare il nuovo controllo. $FieldName contiene il nome del
nuovo controllo.
$MsgExitField Ricevuto quando il cursore sta per lasciare un controllo. $FieldName contiene il nome di quel comando.
$MsgHelp Ricevuto quando l'utente sceglie il tasto ? o F1.
$MsgMandField Ricevuto quando l'utente tenta di accettare un modulo con una o più caselle di immissione testo obbligatorie non riempite.

$FieldName contiene il nome della prima casella di immissione testo obbligatoria non riempita. Per default, il sistema visualizza
un messaggio che informa l'utente del problema. Restituire 0 per impedire la visualizzazione di questa casella.

Nomi controlli del modulo

Ogni controllo in un modulo ha un nome. Negli esempi precedenti, è stato utilizzato un modulo per ottenere le informazioni necessarie per riempire una variabile di tipo EmployeeRecord. Poiché quel record ha un campo denominato FIRST_NAME, è richiesto anche un controllo modulo denominato FIRST_NAME. Quando un utente immette un valore nel controllo modulo FIRST_NAME, le informazioni vengono copiate nel campo record FIRST_NAME.

Nota: Alcuni controlli non supportano i dati. Ad esempio, i pulsanti comando non hanno un valore; creano degli eventi. Perciò, non è necessario avere un campo record per i pulsanti in un modulo.

Attributi aggiuntivi dei controlli

E' possibile specificare attributi aggiuntivi per i controlli del modulo compresi:

Attributi Descrizione
Di sola lettura I dati nel controllo vengono inizializzati dal record di istanza della finestra e non possono essere modificati dall'utente.
Obbligatorio L'utente non può accettare il modulo fino a quando non sono stati forniti i valori per tutti i controlli obbligatori.
Lunghezza immissione Specifica il numero di caratteri che l'utente può immettere nel controllo all'interno di un campo testo.

Esistono altri attributi che interessano solo controlli specifici. Ad esempio, è possibile attivare o disattivare l'unione delle parole per le caselle di testo a più righe.

Tabella

Descrizione

Tabella è una finestra utilizzata per visualizzare una tabella di risultati SQL. Una tabella di risultati SQL è un insieme di righe e di colonne.

Tabella viene utilizzata come un controllo del modulo e consente di:

Le dimensioni delle colonne all'interno di Tabella possono essere modificate. Una sottile barra verticale separa le colonne adiacenti e gli utenti possono riposizionare questa barra per modificare l'ampiezza delle colonne.

L'istruzione di selezione può essere specificata nel file .df o può essere programmata.

Istruzioni Descrizione
DlgSQLSelect Questa istruzione consente al TSD Script di emettere la query SQL indicata e di aggiornare il contenuto del controllo Tabella indicato con i risultati di quella query.

Questa istruzione considera tre argomenti:

  • L'handle della finestra del modulo
  • Il nome del controllo Tabella
  • Un'espressione di stringa che rappresenta un'istruzione SQLSelect

Questo è il modo migliore per spostare i dati da un database a un controllo della tabella.

DlgFieldValue Questa istruzione può essere utilizzata per richiamare una riga selezionata.
Questa istruzione considera tre argomenti:
  • l'handle della finestra modulo
  • il nome del controllo
  • una variabile record che riceve le informazioni dalla riga evidenziata

Le colonne dalla riga vengono copiate nei campi record con nomi identici (ad esempio, la colonna "FIRST_NAME" viene copiata in r.FIRST_NAME).

DlgListBoxInsert Questa istruzione inserisce una nuova riga in Tabella. Questo comando non esegue un'istruzione SQLInsert, ma aggiunge una nuova riga al controllo del modulo indicato.

Questa istruzione considera tre argomenti:

  • l'handle della finestra modulo
  • Il nome del controllo
  • Una variabile record i cui campi devono corrispondere ai nomi delle colonne di Tabella

I valori corrispondenti vengono copiati nelle colonne appropriate e i campi record senza colonne corrispondenti vengono ignorati.

DlgListBoxUpdate Questa istruzione aggiorna una riga selezionata in Tabella. Questo comando non esegue un'istruzione SQLUpdate, ma aggiorna le informazioni nel modulo.

Questa istruzione considera tre argomenti:

  • l'handle della finestra modulo
  • Il nome del comando
  • Una variabile record i cui campi vengono definiti con i nomi delle colonne del controllo Tabella

I valori corrispondenti vengono copiati nelle colonne appropriate. I campi record senza corrispondenze di colonne vengono ignorati.

DlgListBoxDelete Questa istruzione cancella la riga selezionata nel controllo Tabella. Questo comando non esegue un'operazione SQLDelete, ma elimina una riga dal controllo indicato nella finestra modulo.

Questa istruzione considera due argomenti:

  • l'handle della finestra modulo
  • Il nome del controllo Tabella

Esempio di Tabella

Questo esempio crea un file .kb (knowledgebase) denominato Users con una singola procedura pubblica denominata WorkWithUsers.

KNOWLEDGEBASE Users; 
  TYPES 
    UserRecord IS RECORD 
      $Select : String; 
      user_ID : String; 
      user_name : String; 
      user_rights : Integer; 
      END; 
    ROUTINES 
    PROCEDURE WorkWithUsers; 
PRIVATE 
    ROUTINES 
    EVENT UserEvent(REF user: UserRecord) IS; 
VARIABLES 
      i: Integer; 
    ROUTINES 
      PROCEDURE AddUser IS; 
VARIABLES 
        newUser: UserRecord; 
    ACTIONS 
        IF DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent,
           newUser) > 0 AND 
SQLInsert('USERS',newUser) > 0 THEN
           DlgListBoxInsert($Handle,'USERLIST',newUser); 
      END; 
     END (* Add User *); 
     PROCEDURE EditUser IS; 
    ACTIONS 
       IF DlgFieldValue($Handle,'USERLIST',user) 
          > 0 AND 
          DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent
{user},user) > 0 AND 
         SQLUpdate('USERS','USER_ID=''' 
          user.user_ID & '''',user) > 0 THEN 
          DlgListBoxUpdate($Handle,'USERLIST',user);
      END; 
     END (* Edit User *); 
     PROCEDURE DeleteUser IS; 
    ACTIONS 
IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND 
          SQLDelete('USERS','USER_ID='''&user.user_ID&'''')
              > 0 THEN 
          DlgListBoxDelete($Handle,'USERLIST',user);
      END; 
     END (* Delete User *); 
       ACTIONS 
      WHEN $Event IS $MsgCreate THEN 
       DlgSQLSelect($Handle,'USERLIST',user.$select);
      ELSWHEN $MsgSelect THEN 
       WHEN $FieldName IS 'ADD_BUTTON' THEN 
         AddUser; 
       ELSWHEN 'EDIT_BUTTON' THEN 
         EditUser; 
       ELSWHEN 'DELETE_BUTTON' THEN 
         DeleteUser; 
      END; 
      END; 
   END (* User Event *); 
   PROCEDURE WorkWithUsers IS; 
VARIABLES 
     UserWindow: WINDOW; 
     user: UserRecord; 
    ACTIONS 
     user.$select = 'SELECT * FROM USERS'; 
     DlgCreate($Desktop,userWindow,
               'USERS.DFC [WORKWITHUSERS]',
               UserEvent{user}); 
   END (* Work With Users *); 

Spiegazione dell'esempio

Il ruolo di WorkWithUsers è quello di creare un modulo con i seguenti controlli:

L'handler degli eventi UserEvent per il modulo elabora questi eventi:

Tabella trattiene solo le informazioni specificate dalla propria descrizione della colonna. Questa può essere una sottoserie delle colonne contenute in una tabella di risultati SQL. Quando si utilizza il comando DlgFieldValue per richiamare una riga dal controllo Tabella, vengono restituiti solo i campi che corrispondono alle colonne in quel controllo. Potrebbe essere necessario eseguire SQLSelectInto o SQLSelect per poter completare il resto del record.

Creazione dei moduli

TSD Script crea un nuovo modulo in un processo che coinvolge diversi passi:

Nota: I dati nella variabile di istanza del record sovrascrivono i valori di inizializzazione forniti nel file del modulo.

Moduli modali

Un modulo modale è un modulo in cui il programma attende che l'utente accetti o annulli il modulo prima di procedere. Quando viene visualizzata una casella di dialogo modale, non è possibile selezionare altre finestre.

I moduli modali vengono creati con DlgBox. L'istruzione che segue DlgBox non viene eseguita fino a quando l'utente non termina con il modulo che sta creando. Le informazioni specificate dall'utente vengono restituite nel quarto argomento a DlgBox. Questa è la variabile record di emissione.

I moduli modali devono essere riservati innanzitutto ai messaggi di errore importanti o alle caselle di dialogo con problemi critiche dove l'utente non può continuare senza rispondere a una query. Un esempio di questo tipo di modulo può essere un messaggio relativo alla cancellazione di file.

Moduli non modali

Un modulo non modale è un modulo nel quale l'applicazione non attende l'utente prima di procedere. Questo significa che l'utente è in grado di passare ad altre finestre durante la visualizzazione del modulo.

I moduli non modali vengono creati con DlgCreate. Quando si effettua una chiamata di DlgCreate, il processo di creazione di un modulo viene impostato su "in funzione". Tuttavia, l'esecuzione della successiva istruzione avviene simultaneamente.

Il nuovo modulo dispone della propria interfaccia utente e del proprio programma (il proprio handler degli eventi). Continua ad esistere fino a quando l'utente non accetta o non annulla il modulo, oppure fino a quando un'altra parte dell'applicazione non gli invia un messaggio di chiusura ($MsgClose).

Nota: Nella programmazione basata sugli eventi, si preferiscono i moduli non modali.

Moduli separati

Il TSD Script offre un tipo di modulo speciale con "pagine" separate. Per spostarsi da una pagina all'altra, l'utente sceglie i separatori.

Si creano i moduli separati nella Progettazione d'interfaccia del Developer's Toolkit specificando uno o più moduli da combinare. Al momento dell'esecuzione, è possibile utilizzare questi moduli nel modo in cui si utilizzano altri tipi di moduli. Possono essere creati con DlgBox o DlgCreate. Per gestire i loro eventi, è possibile creare un handler degli eventi.

Quando si gestiscono i moduli separati, è necessario tenere a mente quanto segue:


Manuale per la programmazione Tivoli Service Desk 6.0 Developer's Toolkit Script

Ritorna all'Indice analitico

Copyright