Manuale per la programmazione Tivoli Service Desk 6.0 Developer's Toolkit Script
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:
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. |
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.
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.
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 Quando l'utente seleziona un pulsnate con Accetta proprietà, TSD Script copia
automaticamente il contenuto dei controlli del modulo nei |
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 |
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.
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.
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.
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.
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.
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 |
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.
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 è 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:
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:
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:
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:
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:
|
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 *);
Il ruolo di WorkWithUsers è quello di creare un modulo con i seguenti controlli:
L'handler degli eventi UserEvent per il modulo elabora questi eventi:
~ Il messaggio $MsgSelect viene creato con il
nome del pulsante comando, EDIT_BUTTON, inoltrato in
$FieldName.
~ L'handler degli eventi chiama la procedura
EditUser per gestire questo evento.
EditUser utilizza innanzitutto l'istruzione DlgFieldValue
per chiamare il valore della riga selezionata.
~ Utilizza poi il modulo EDITFORM da USERS.DFC per creare un modulo
nel quale l'utente può apportare le modifiche desiderate.
~ Quando l'utente accetta questo modulo, l'istruzione SQLUpdate
viene utilizzata per aggiornare la riga nella tabella
USERS e DlgListBoxUpdate
viene utilizzata per aggiornare la riga corrispondente nel controllo
Tabella USERLIST.
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.
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.
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.
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.
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