Secure Global Desktop 4.40 Administration Guide > Users and Authentication > Login Script Tcl Commands and Procedures

Login Script Tcl Commands and Procedures

The login scripts supplied with SGD use several Tcl commands and procedures for communication with the application server.

The TCL commands are commands that are defined in Execution Protocol Engine (ExecPE) and can be used in your own login scripts to provide control over the connection to the application server, and the display of the SGD authentication and progress dialogs.

The TCL procedures are defined in the login scripts only and can be used to provide more control over the authentication dialog.

The following Tcl commands and procedures control the display of the SGD authentication dialog:

authrequest
authenticate
authenticate2
customauthenticate
userauthenticate

The following Tcl commands control the display of the SGD progress dialog when launching an application:

loaderror
clienttimer
canceltimer
progress

The following Tcl commands control the connection to the application server:

setbuffer
locallaunch
tarantella
sgdconnect

authrequest

authrequest
  [ -normal | -changed ] 
  -showuser 0|1 
  -title title 
  -message message
  -customuserlabel 0|1
  -userlabel label 
  -custompasswdlabel 0|1
  -passwdlabel label
  -showpasscache 0|1
  -showsmartcard 0|1
  -isuserdialog 0|1|2

This is a Tcl command that displays a dialog box that indicates a problem with the user name or password.

Typically you do not call the authrequest command directly in your login scripts. Instead, you use the defined Tcl procedures to call this command with the required arguments.

This command has the following arguments.

Argument	Description
`-normal`	Specifies that the password is incorrect.
`-changed`	Specifies that the password has expired.
`-showuser`	Specifies that the user name field is displayed.
`-showpasswd`	Specifies that the password field is displayed.
`-title`	Specifies the title used for the authentication dialog.
`-message`	Specifies the message that is displayed in the authentication dialog.
`-customuserlabel`	Specifies whether to use a customized label for the user name field.
`-userlabel`	Specifies the customized label to use for the user name field.
`-custompasswdlabel`	Specifies whether to use a customized label for the password field.
`-passwdlabel`	Specifies the customized label to use for the password field.
`-showpasscache`	Specifies whether the Save this password check box is displayed.
`-showsmartcard`	Specifies whether the smart card option is displayed.
`-isuserdialog 0\|1\|2`	Specifies whether a customized authentication dialog is used. Specify one of the following: `0` - means do not check whether the user name has changed `1` - means check whether the user name has changed and reconnect to the application server if necessary `2` - means the use the default SGD behavior if the user name has changed

The following example displays a dialog box that says the password is incorrect:

authrequest -normal

authenticate

Displays a dialog box that indicates a problem with the user name or password.

This is a Tcl procedure that calls the authrequest command with the following options:

authenticate [ -normal | -changed ]

authenticate2

Displays a dialog box that indicates a problem with the user name or password. Allows you to use your own title for the dialog and display your own message. You can also control whether the user name and password fields display.

This is a Tcl procedure that calls the authrequest command with the following arguments:

authenticate2 
  [ -normal | -changed ] 
  -showuser 0|1 
  -showpasswd 0|1 
  -title title 
  -message message

customauthenticate

Displays a dialog box that indicates a problem with the user name or password. Allows you to fully customize the authentication dialog.

With this procedure, the ExecPE does not check the text the user types in the user name field. If SSH is used as the connection method for the application and the user changes the user name, the ExecPE does not break the connection and re-connect as the new user name. This can cause application launches to fail. If you are using SSH and allow the user to change the user name, use the userauthenticate procedure instead.

This is a Tcl procedure that calls the authrequest command with the following arguments:

customauthenticate 
  [ -normal | -changed ] 
  -showuser 0|1 
  -title title 
  -message message
  -customuserlabel 0|1
  -userlabel label
  -custompasswdlabel 0|1
  -passwdlabel label
  -showpasscache 0|1
  -showsmartcard 0|1

userauthenticate

Displays a dialog box that indicates a problem with the user name or password. This procedure allows you to fully customize the authentication dialog.

This procedure is the same as customauthenticate except that it does check whether the user has changed the user name. If the user name is changed, the ExecPE breaks the connection to the application server and reconnects as the changed user.

This is a Tcl procedure that calls the authrequest command with the following arguments:

userauthenticate 
  [ -normal | -changed ] 
  -showuser 0|1 
  -showpasswd 0|1
  -title title 
  -message message
  -customuserlabel 0|1
  -userlabel label
  -custompasswdlabel 0|1
  -passwdlabel label
  -showpasscache 0|1
  -showsmartcard 0|1

loaderror

loaderror error

Allows you to override the error message returned by the login script. You can use this function, for example, to replace the standard login script error messages with your own message. If the application launch fails, the error is displayed in the progress dialog and in the log files.

clienttimer

clienttimer [ time ] [ message ] [ timers ]

Displays message in the progress dialog box for the specified time. The progress bar has timers sections in total. The following is an example:

clienttimer 10 "Launching the application" 4

canceltimer

canceltimer

Cancels the clienttimer command. This command has no arguments.

progress

progress [ message ]

Displays message in the progress dialog box. The following is an example:

progress "Initializing..."

setbuffer

setbuffer [ -buffer num ] [ -output 0|1 ]

Defines the number of bytes to read from the application server.

Argument	Description
`-buffer num`	Specifies the number of bytes. Default is 1.
`-output 0\|1`	Turns output on (1) or off (0). Default is 1.

The following is an example:

setbuffer -buffer 1000

locallaunch

locallaunch [ -start ] [ -abort ] [ -user launchspec -root launchspec ]

Optimizes launch in the situation where the application server is also the SGD server.

Argument	Description
`-start`	Starts an optimized launch.
`-abort`	Aborts the optimized launch and reverts to the standard connection method.
`-user launchspec`	Defines the connection methods to use for launching applications on the SGD server when the user is not the UNIX or Linux root user. You can specify different behavior for applications that are detached on launch (background applications) and those that are not (foreground applications). The `launchspec` can be one of the following: 0 - Launches all applications using the Connection Method defined for the application object. 1 - Background applications use `/bin/su`. Foreground applications use the application object's Connection Method. 2 - Background applications use the application object's Connection Method. Foreground applications use `/bin/su`. 3 - Launches all applications using `/bin/su`. The default is `1`.
`-root launchspec`	Defines the connection methods to use for launching applications on the SGD server when the user is the UNIX or Linux root user. You can specify different behavior for applications that are detached on launch (background applications) and those that are not (foreground applications). The `launchspec` can be one of the following: 0 - Launches all applications using the Connection Method defined for the application object. 1 - Background applications use `/bin/su`. Foreground applications use the application object's Connection Method. 2 - Background applications use the application object's Connection Method. Foreground applications use`/bin/su`. 3 - Launches all applications using `/bin/su`. 4 - Launches all applications using the Connection Method defined for the application object. The default is `3`.

The following is an example:

locallaunch -abort

tarantella

tarantella
 [ -nosocket ] 
 [ -portnumber num ] 
 [ -thirdtiershell shell ]

This command is used to configure the connection to the application. You must configure the connection before you use the sgdconnect command.

Argument	Description
`-nosocket`	Specifies that the application is to be started by some other means and must be implemented by whoever is creating the script, for example by using Expect's `spawn` command. This can only be done with applications that do not require a permanent connection, such as X applications. This command is useful if you have an unusual application server, or if you need to integrate with an existing launch mechanism.
`-portnumber num`	Overrides the port used to make the connection to the application server. If you use this option, you must execute the `tarantella` command before the `sgdconnect` command, otherwise the port number is ignored.
`-thirdtiershell shell`	Specifies the shell to use on the application server, for example `/bin/sh`.

The following example connects to the application server on TCP port 5999:

tarantella -portnumber 5999

sgdconnect

sgdconnect

Instructs the Execution Protocol Engine (ExecPE) to connect to the application server. This command has no arguments.

Most of the SGD login scripts use sgdconnect to make the connection. If you want to handle the connection to the application server yourself, you must ensure that your script does not use this command.

The wcpwts.exp standard login script is an example of a login script that does not use this command to connect to an application server.

Related Topics
Login Scripts Supplied With SGD Login Script Error Messages Increasing the Launch Timeouts in the Login Scripts Login Script Variables An Application Does Not Start