CDS188

Launch Application

Last Revised: 10/09/18

This routine is used to launch an application on the local workstation.  It can also be used to launch an interactive bbj application from pro5 using java web start.

Supported Configurations
Workstation	Dynamo Tools Terminal Type	Terminal Emulator
Windows PC, Apple Mac, or Linux Workstation	S	Dynamo Web Start thin client
Windows PC	f	FacetWin
Windows PC	P	Ericom PowerTerm Interconnect
Linux Workstation	L	Ericom PowerTerm for Linux
Axel Terminal in GUI Mode	L	Ericom PowerTerm for Linux
Apple Mac	M	Ericom PowerTerm for Apple Mac
Windows PC, Apple Mac, Linux workstation, Axel Terminal in GUI Mode	P	Ericom PowerTerm WebConnect

Calling Format:

CALL "CDS188", ERR=NA, Y$, CMD$, ARG$, { OPT$, TITLE$, NSID$}

Set Global Variable "SMS_CDS188" to "D" to enable debug mode, where the command sent to the workstation will be displayed in a prompt.

Input Data Elements
ERR=NA	Branch to line label NA if the Terminal Type is not one of those shown above.
Y$	Optional session control variable
CMD$	Command to be executed. null Workstation Type CMD$ Windows PC launch application based on extension of ARG$.  This would be the default web browser if ARG$ is a URL, Microsoft Word if the extension is .doc, Microsoft Excel if the extension is .xls, Adobe Reader if the extension is .pdf, etc. Linux or Axel launch default web browser (typically firefox) Apple Mac launch workstations default web browser (typically be safari, firefox, internet explorer, etc.) program name Will launch the program name specified.  Note that in the case of Windows, the program name has to be in the DOS 8.3 file format.  So instead of C:\Program Files\... you would need C:\PROGRA~1\....  If the program is in the PATH then of course you don't need the full path to the executable.  The disadvantage to this is that you cannot guarantee what the DOS 8.3 file name is on all PC's.  So the best practice is to keep all folders and file names to 8 characters or less, excluding the characters in the file extension.  Note that any file names are relative to the workstation and not the server.  Windows does not display any error message if the program does not exist.
ARG$	CMD$ ARG$ null (web browser) Pass URL such as www.excellware.com not null (other workstation application) Pass file or document name for application to open.  When the workstation is a PC ARG$ may need to be in the DOS 8.3 file name format depending on the application.
OPT$	If the workstation or terminal emulator is not one of the supported types, then you can pass OPT$ to have CDS188 prompt the user to invoke the application manually.  Regardless of OPT$, CDS188 will EXIT 99 causing the calling program to take the ERR= branch. B Prompt user: "Point your web browser to..." Y Prompt user: "Open file..." other No prompt
TITLE$	When CDS188 is called to open a web page from an application launched by the Dynamo Tools Graphical Menu, the web page will be opened within a BBj Window within the MDI framework, much like any other menu selection. The TITLE$ argument will appear in the window title bar.
NSID$	The Namespace ID is used in the same situation as the TITLE$ argument and provides a mechanism to automatically close the MDI Window. This might be done when the user clicks on a Save or Cancel button. It is typically set to STR(DEC(INFO(3,0)) + "someDescriptiveText. The application or servlet used to close the window should execute this code: declare BBjNamespace ns! ns! = BBjAPI().getGlobalNamespace() ns!.setValue(NSID$, "anyValue")

Example to launch a web browser to www.excellware.com and prompt the user if using a non-supported terminal emulator
1010 CALL "CDS188",ERR=1020,Y$,"","www.excellware.com","B"
Example to launch Microsoft Word opening a specific document located on the PC
1010 CALL "CDS188",ERR=1020,Y$,"","C:\docs\letter.doc","Y"
Example to launch Microsoft Word opening a specific document located on the server
1010 CALL "CDS188",ERR=1020,Y$,"","\\server\docs\letter.doc","Y"
Example to launch Microsoft Word opening a document "C:\Documents and Settings\Len Krause\My Documents\Excellware\cust\rl\agreement.doc" Note that DOS 8.3 file names are used and spaces are excluded.  Best practice is to store documents accessed this way in folders and document names of 8 characters or less (not including the file extension).
1010 CALL "CDS188",ERR=1020,Y$,"",  "\DOCUME~1\LENKRA~1\MYDOCU~1\EXCELL~1\CUST\RL\AGREEM~1.DOC"
Example to launch a DOS window displaying a directory including DOS 8.3 name, and keeping the window open
1010 CALL "CDS188",ERR=1020,Y$,"CMD","/K DIR /X"
Example to launch a PDF viewer, typically Adobe Reader, for a file located on the server
1010 CALL "CDS188",ERR=1020,Y$,"","\\server\docs\letter.pdf"
Example to launch windows explorer to the C:\Program Files folder
1010 CALL "CDS188",ERR=1020,Y$,"explorer","C:\Program Files"
Example to launch windows notepad to a new empty document
1010 CALL "CDS188",ERR=1020,Y$,"notepad"
Example to launch the Basis Enterprise Manager from pro5 Requirements: bbj version 9, bbj running in a JDK and not a JRE, Enterprise Manager 'Run Server' option checked for the 'Web Server' on the Servers tab, Enterprise Manager 'Run Enterprise Manager' option box checked on the JNLP Configuration page.
1010 CALL "CDS188",ERR=1020,Y$,"","http://localhost:8888/jnlp/em.jnlp","B"