1. CALL CLIENT "SYSTEM", "C$RUN" or "C$SYSTEM"
2. CALL CLIENT "ShellExecuteA" ...
3. CALL CLIENT "MYPROG" (where MYPROG is a COBOL program)

1. CALL CLIENT "SYSTEM", "C$RUN" or "C$SYSTEM"

The SYSTEM, C$RUN and C$SYSTEM library routines allow a program to run an operating system command line as if it was executed from a command prompt, shell, script, batch file, or shortcut.

SYSTEM runs the command synchronously so that the program waits for the command to complete before continuing.

C$RUN runs the command asynchronously so that the program continues to run in parallel with the command.

C$SYSTEM combines the functionality of SYSTEM and C$RUN and allows a command to be run synchronously or asynchronously depending on a "flags" parameter.

Add the CLIENT clause to the CALL statement in order to run the command on the client-side. The isCOBOL framework ignores the CLIENT clause when not running in thin client mode. So CALL CLIENT is safe to use in programs that run in both thin client and local modes.

For example, to launch the Windows calculator program:

CALL CLIENT "C$RUN" USING "calc".

If Microsoft Excel is in the client-side PATH then you could launch it with:

CALL CLIENT "C$RUN" USING "excel.exe".

However, usually excel.exe is not in the PATH. So you would need to specify a full path such as in:

CALL CLIENT "C$RUN" USING
  "C:\Program Files\Microsoft Office\OFFICE11\excel.exe".

2. CALL CLIENT "ShellExecuteA" ...

The Windows API ShellExecute function opens or prints a specified file. This function is located in shell32.dll. You can use the ShellExecute function to start an application assocated with a given document extension without knowing the name of the associated application. For example, you could start the Paintbrush program by passing the filename ARCADE.BMP to the ShellExecute function.

For example, the following program will open file.csv with whatever application is associated with the .csv file extension. If Microsoft Excel is installed on the system then it is most likely the application that will launch:

ID DIVISION.
PROGRAM-ID. LAUNCHCSV.
DATA DIVISION.
WORKING-STORAGE SECTION.
78 SW-SHOWNORMAL VALUE 1.
77 RETURN-VAL USAGE LONG.
PROCEDURE DIVISION.
MAIN-LOGIC.
 * SEE http://support.microsoft.com/kb/238245
 CALL CLIENT "C$SETENV" USING 
     "dll_convention", "1".
 CALL CLIENT "shell32.dll".
 CALL CLIENT "ShellExecuteA" USING
  BY VALUE 0,
  BY REFERENCE "open",
  BY REFERENCE "file.csv",
  BY REFERENCE "",
  BY REFERENCE "",
  BY VALUE SW-SHOWNORMAL
  RETURNING RETURN-VAL.
 IF RETURN-VAL < 32 THEN
  DISPLAY "ERROR: ShellExecute() returned ",
   RETURN-VAL
 END-IF.
 STOP RUN.

3. CALL CLIENT "MYPROG" (where MYPROG is a COBOL program)

If a program named MYPROG is available in the client-side class path, then a program running on the server can call it using CALL CLIENT "MYPROG" and can pass it input, output or input-output parameters of any type by reference or by value just as if it was calling the program on the server.

For example, you could compile the following program and add it to your client-side jar file or have your installer put it on the client in the class path specified when your users launch the thin client:

ID DIVISION.
PROGRAM-ID. MYCALC.
PROCEDURE DIVISION.
 CALL "C$RUN" USING "calc".

CALL CLIENT "MYCALC".

Note that there are differences in behavior of C$RUN/C$SYSTEM between isCOBOL and ACUCOBOL-GT. For example, calls relying on UNIX/Linux shell syntax for redirection of standard streams should be made using the SYSTEM routine.

See http://www.veryant.com/support/phpkb/question.php?ID=113 for more information and workarounds for C$RUN/C$SYSTEM if you need platform specific functionality.

1. How do I set up isCOBOL Server (Application Server) and Thin Client?
2. How do I debug a program running in thin client mode?
3. How do I use Java Web Start to automatically download and launch the thin client?
4. How do I capture client side errors when using a different look and feel (e.g. Nimbus)?
5. With thin client is there a way to update and push changes to programs live (on the fly), without having to kill and restart the isCOBOL Server?
6. How do I use secure transport (SSL) with the isCOBOL thin client?
7. How do I avoid having to edit the Java security policy to allow isCOBOL thin client applet to connect?
8. The COBOL program suddenly terminates on the server and leaves thin client running with a blank screen
9. How can I get the system-information data from the client computer?
10. How do I download files from server to client using isCOBOL Thin Client?
11. What are the Java version requirements on the client and server? Do they need to match?
12. How do I resolve the error 'Application Blocked by Java Security' working with jnlp?
13. Is there a way to simulate users and load-test the thin client?
14. The user name shown by the -panel is the PC Name. Is it possible have the user id of our application?
15. How can I get the local username?
16. Is there a way to distribute multiple client connections on different servers?
17. What's the meaning of the error 'Software Incompatiblity'