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 the Execution Protocol Engine component of SGD. The commands can be used in your own login scripts to provide control over the connection to the application server, and the display of the SGD Application Authentication and Progress dialogs.

The Tcl procedures are defined in the login scripts only. The procedures can be used to provide more control over the SGD Application Authentication dialog.

Controlling the SGD Application Authentication Dialog

The following Tcl commands and procedures are used to control the display of the SGD Application Authentication dialog when starting applications:

authrequest
authenticate
authenticate2
customauthenticate
userauthenticate

`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 Tcl command 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` - Do not check whether the user name has changed `1` - Check whether the user name has changed and reconnect to the application server if necessary `2` - 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 Tcl procedure 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. You can 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 Tcl procedure calls the authrequest command with the following arguments.

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

`customauthenticate`

Displays a dialog box that indicates a problem with the user name or password. You can fully customize the authentication dialog.

With this procedure, the Execution Protocol Engine does not check the text the user types in the user name field. If Secure Shell (SSH) is used as the connection method for the application and the user changes the user name, the Execution Protocol Engine does not break the connection and reconnect as the new user name. This can cause applications to fail to start. If you are using SSH and allow the user to change the user name, use the userauthenticate procedure instead.

This Tcl procedure 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. You can 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 Execution Protocol Engine breaks the connection to the application server and reconnects as the changed user.

This Tcl procedure 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

Controlling the SGD Progress Dialog

The following Tcl commands are used to control the display of the SGD progress dialog when starting applications:

loaderror
clienttimer
canceltimer
progress

`loaderror`

loaderror error

You can use this Tcl command 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 fails to start, the error is displayed in the progress dialog and in the log files. See Login Script Error Messages.

`clienttimer`

clienttimer [ time ] [ message ] [ timers ]

This Tcl command 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

This Tcl command cancels the clienttimer command. This command has no arguments.

`progress`

progress [ message ]

This Tcl command displays message in the progress dialog box. The following is an example.

progress "Initializing..."

Controlling the Connection to the Application Server

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

setbuffer
locallaunch
tarantella
sgdconnect

`setbuffer`

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

This Tcl command 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 ]

This Tcl command starts an application when the application server is also the SGD server. This is known as an optimized launch.

Argument	Description
`-start`	Starts an optimized launch.
`-abort`	Stops the optimized launch and reverts to the standard connection method.
`-user` `launchspec`	Defines the connection methods to use for starting applications on the SGD server when the user is not the UNIX or Linux platform 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` - Starts 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` - Starts all applications using `/bin/su` The default is `1`.
`-root` `launchspec`	Defines the connection methods to use for starting applications on the SGD server when the user is the UNIX or Linux platform 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` - Starts 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` - Starts all applications using `/bin/su` `4` - Starts 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 Tcl command is used to configure the connection to the application server. 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 application start 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 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.

Exit Print View
Oracle Secure Global Desktop Administration Guide for Version 4.6

Oracle Secure Global Desktop Administration Guide for Version 4.6