Connect Method
Establishes a connection with a remote host. Corresponds to the Connect action.
App.Connect([connection][,alreadyConnected][,onFirstRecieve)
Client support
Newlook Smartclient
Newlook Server
Use
This method can be used in one of the following three ways:
- Connect to an existing connection (i.e. one that has been previously defined with the Connections editor ).
- Dynamically create or modify a connection definition, then connect to it, at run time.
- Open a tn5250 URL hyperlink.
Connect to an existing connection definition
Establishes a connection with a defined connection definition.
Parameters
connection - (String, Optional)
Specifies the predefined connection definition to use.
alreadyConnected - (Integer, Optional)
Specifies the action to take if Newlook is already connected. Refer to AlreadyConnected constants for a list of pre-defined values that can be used with this parameter. If alreadyConnected is left blank, nlConnPrompt is used.
onFirstReceive- (String, Optional)
Introduced in Version 11.1.
Specifies the name of the script or macro to run when this connection is established, and a screen is received. This parameter is particularly useful in multi-session environments where you want to provide a single call-back to notify the visible session that the current session has connected. If App.OnReceive is also set, the logic specified in the onFirstReceive parameter of the Connect method is executed first.
Use
Leaving the Connect parameter blank forces the Connect Dialog to be displayed when the script runs. This option may be suitable if you wish to give users a choice of pre-defined connections.
Fig 1. Connect Dialog that displays if the Connection parameter is left blank.
SMARTCLIENT ONLY
Note: the option to generate the Connect dialog by leaving the Connection parameter blank is not supported in Newlook Server.
EXAMPLE
The following script connects to the pre-defined connection "Test Connection" and runs the "Events.OnFirstReceive" function after a connection is established.
J SCRIPT
function ConnectToHost()
{
App.Connect("Test Connection", nlConnTerminate, "Events.OnFirstReceive");
}
Connect to a dynamically created or modified connection definition
Dynamically create or modify a connection definition at run-time, and connect to it.
Parameters
connection - (String, Optional)
Specifies a connection string. To dynamically modify or create a connection at run-time a valid connection string must be specified, with each connection property specified as an input=val pair, where 'input' is a string that is the name of the Connection property and 'val' is the value being supplied for that property.
alreadyConnected - (Integer, Optional)
Specifies the action to take if Newlook is already connected. Refer to AlreadyConnected constants for a list of pre-defined values that can be used with this parameter. If alreadyConnected is left blank, nlConnPrompt is used.
onFirstReceive- (String, Optional)
Introduced in Version 11.1.
Specifies the name of the script or macro to run when this connection is established, and a screen is received. This parameter is particularly useful in multi-session environments where you want to provide a single call-back to notify the visible session that the current session has connected. If App.OnReceive is also set, the logic specified in the onFirstReceive parameter of the Connect method is executed first.
Use
Properties that can be specified in a Connection string include:
- Connection - a unique name used to identify the connection being created or specify the connection being modified.
- Network Address - the computer name or IP address of the server you are connecting to.
- Network Port - the TCP/IP Port to connect to. The default is 23.
- Locale - the locale needs to be specified with its locale ID (LCID) instead of the locale name. For a list of locales and their corresponding LCIDs refer to Microsoft's Windows Language Code Identifier Reference.
- Client Code Page - the desired code page to use for this connection.
- Host Code Page - the desired code page to use for this connection.
- Calendar - the default calendar type displayed in date combo box controls for this connection.
- Date Format - the default date format for this connection.
- Numeric Format - the default numeric format applied to numbers for this connection.
- Currency Symbol - the default symbol used to identify currency for this connection.
- Decimal Symbol - the default decimal separator symbol for this connection.
- Thousand Symbol - the default thousand separator symbol for this connection.
- Negative Symbol - the default symbol used to denote negatives for this connection.
- Display Device - the host device description to use for display sessions for this connection.
- Printer Device - the printer device description to use for printer sessions for this connection.
TIP:
To override an existing connection definition, you must specify the name of the connection you wish to override in the Connection property of the Connection string.
It is also possible to modify printer connections using this action. This is useful if you need to create a generic printer connection that can then be modified for different IP addresses and printer devices.
Note that it is not possible to override Advanced print settings or the HPT/SCS setting.
EXAMPLES
The following script creates the connection "MyConnection", and then connects to it:
J SCRIPT
function ConnectToHost()
{
App.Connect("Connection=MyConnection;Network Address=192.168.1.1;Network Port=23;Display Device=JULIE1;Date Format=MM/dd/yyyy", nlConnTerminate, "Events.OnFirstReceive");
}
The following script connects to the existing "MyHost" connection definition, overwriting the Network Address, Display Device and Date Format properties in the connection definition with the values defined in the method's parameters. All other values in the existing connection definition will be unchanged:
J SCRIPT
function ConnectToMyHost()
{
App.Connect("Connection=MyHost;Network Address=acme.looksoftware.com;Display Device=JULIE1;Date Format=MM/dd/yyyy", nlConnTerminate);
}
The following script connects to the existing "GenericPrinter" definition with custom Network Address and Printer Device properties:
J SCRIPT
function ConnectToPrinter()
{
App.Connect("Connection=GenericPrinter;Network Address=192.168.1.1; Printer Device=TESTPRT", nlConnTerminate);
}
Connect to a Telnet 5250 URL
Specifies the Telnet 5250 URL to connect to.
Parameters
connection - (String, Optional)
Specifies the telnet 5250 URL to connect to.
alreadyConnected - (Integer, Optional)
Specifies the action to take if Newlook is already connected. Refer to AlreadyConnected constants for a list of pre-defined values that can be used with this parameter. If alreadyConnected is left blank, nlConnPrompt is used.
onFirstReceive- (String, Optional)
Introduced in Version 11.1.
Specifies the name of the script or macro to run when this connection is established, and a screen is received. This parameter is particularly useful in multi-session environments where you want to provide a single call-back to notify the visible session that the current session has connected. If App.OnReceive is also set, the logic specified in the onFirstReceive parameter of the Connect method is executed first.
Use
To connect to a telnet 5250 session, use the following syntax:
tn5250://[username]:[password]@IP address:[port number]/[device name]:[case-sensitive]
nl5250://[username]:[password]@IP address:[port number]/[device name]:[case-sensitive]
To connect to a secure telnet 5250 session, use the following syntax:
tn5250s://[username]:[password]@IP address:[port number]/[device name]:[case-sensitive]
nl5250s://[username]:[password]@IP address:[port number]/[device name]:[case-sensitive]
- Username - specify the username you wish to connect with (optional). If a username and password are specified, they will be used to automatically sign in to the host.
- Password - the password for the specified username (optional). If a username and password are specified, they will be used to automatically sign in to the host.
- IP Address - the computer name or IP address of the server you are connecting to.
- Port number - the TCP/IP Port to connect to (optional). If left blank this parameter defaults to 23.
- Device name - the host device description to use for display sessions for this connection (optional).
- Case-sensitive - determines whether the case of credentials will be respected. Add the case-sensitive parameter if the host you are connecting to requires case sensitive credentials.
EXAMPLES
The following script connects to the host via a tn5250 URL with the username JULIEM and password ab123AB with the case sensitive option turned on:
J SCRIPT
function 5250Connect()
{
App.Connect("tn5250://JULIEM:[email protected]:23/:case-sensitive", nlConnTerminate);
}
Limitations of the connect method in the runtime client:
- It is only possible to have a single session of the runtime client open at any one time. Regardless of the AlreadyConnected parameter that is specified in the method, all instances of the Connect method in the runtime client will behave as though ConnTerminate has been specified. Use Smartclient to test any macros using the Connect action with an AlreadyConnected parameter of ConnNewWindow or ConnPrompt.
Returns
Returns a Boolean indicating the success or failure of the method.
Applies To
See Also
Connect Action | DBConnect Method | Sessions | OnCustomEvent property