Using the LSREX API call using VS COBOL

Document Sample
Using the LSREX API call using VS COBOL Powered By Docstoc
					29 September 1998
LSREX (Lightspeed Remote EXecution) API:

- Introduction.
- Calling LSREX.
- - Parameters.
- - - Commandline.
- - - Timeout.
- - - Reserved.
- - - Returncode.
- - Making the call.
- - Linking your application.
- - Relinking your application (Lightspeed upgrades).
- - The “[:\” drive.
- - The <sourcefile> Open File dialog via “@”.
- - - Providing a filemask via [M=<mask>].
- - - Changing the default drive/directory via [P=<path>]
- - - Specifying a viewer via [V=<viewer>].
- - - Returning the selected file via [F=c,r,l].
- - The <targetfile> Save As dialog.
- - - Providing a default filename via [M=<file>].
- - - Changing the default drive/directory via [P=<path>].
- The LAUNCH command.
- The DISPLAY/DISP command.


LSREX is an API (Application Programmer’s Interface) and provides access to PC
resources from VS applications. A VS programmer, developing an application in VS
COBOL, for example, may issue DOS commands when their application is executed in a
Lightspeed Virtual Terminal window (the DOS-based VT, Windows 3.x-based VSTW or
Windows 95/98/NT-based LSVT).

Any application may be launched. The programmer provides a 128-byte DOS command
line to the API. Virtual Terminal launches the command verbatim. When the command
completes, the DOS errorlevel is returned to the COBOL caller and their program
resumes. Issuing the command “NOTEPAD C:\AUTOEXEC.BAT,” for example, will
launch notepad.

The purpose of this writing is to document all aspects of LSREX, including, until now,
undocumented features of LSREX. Each of LSREX’s four parameters will be discussed
along with instructions to link LSREX into your application. Additionally, a common use
of LSREX is to execute the Lightspeed utilities that copy files between the VS and PC:
VMODE and VCOPY. LSREX support within each client has been optimized for
VMODE and VCOPY and several internal, undocumented features were added just for
LSREX callers of VCOPY. Those features were added, for the most part, to provide
special services to implement Wang OFFICE Import/Export and Lightspeed OfficeLink
Therefore, the internal features of VCOPY will be exposed in this document.

Calling LSREX:

LSREX is distributed with Lightspeed for the VS (LSNVS/VS) and is expanded to the
library LSAPI.

LSREX requires four parameters:

- A 128 byte NULL terminated commandline.
- A fullword binary timeout
- A halfword binary reserved field
- A halfword binary returncode.

COMMANDLINE: The commandline MUST be NULL terminated; the last byte of the
command MUST be a low value (hex 0). This can be accomplished in two ways. The
first method is to split the commandline into the command portion and the trailing NULL:

       01     COMMANDLINE.
              02  REX-CMD                   PIC X(127).
              02  FILLER                    PIC X(1) VALUE LOW-VALUE.

       CALL “LSREX” USING COMMANDLINE, ..., ..., ..., .

The more robust method is to use the STRING verb:

       01     COMMANDLINE                   PIX X(128).


       CALL “LSREX” USING COMMANDLINE, ..., ..., ..., .

TIMEOUT: The timeout must be a four-byte binary number and is the timeout in
milliseconds. COBOL BINARY elements are two-byte integers. The old style to
represent a four-byte binary integer was:

       01     FOUR-BYTE-INTEGER.
              02   FOUR-BYTE-INTEGER-HIGH                 BINARY.
              02   FOUR-BYTE-INTEGER-LOW                  BINARY.
The proper way to specify a fullword integer is:

       01      TIMEOUT               PIC S9(9) BINARY.

The picture clause increases the size of the binary element from two bytes to four. This
code will generate a level-4 compiler warning indicating that the picture clause has
affected the size.

RESERVED: The third parameter is a two-byte binary integer and must be zero. A value
of 128 will allow VCOPY commands to bypass the directory scan secure logic. Users
will be able to access files in libraries and volumes that they would otherwise not have
access to. This backdoor is only available to rex callers of VCOPY.

       01      RESERVED              BINARY VALUE ZERO.

RETURNCODE: The returncode is a two-byte binary integer. A value between zero and
255 indicate success. This is the DOS errorlevel of the application that was called. A
value of ten, for example, indicaes that the requested application was executed, but it
retuened with a DOS errorlevel of 10.

       01      RETURNCODE            BINARY.

The following table lists all LSREX return codes:

       Return Code            Meaning
       0-255                  Success; return code (errorlevel) from DOS command.
       1000                   Unable to open control file.
       1002                   Unable to read control record.
       1003*                  Non-Lightspeed terminal task.
       1004                   Unable to create VT response task
       1005                   Unable to transmit DOS command.
       1006                   The timeout in TIMEOUT has expired.
       1007*                  This version of LSREX is not compatable with LSNVS/VS.
       2000-2999              Error from MSMAP + 2000.

Note 1: A returncode of 1003 indicates that the workstation executing your program is
not running in a Lightspeed Virtual Terminal window. It is probably executing on a real
4230 or 2256C workstation. Your application can only issue DOS commands via
LSREX if it is running on a Lightspeed client.

Note 2: A returncode of 1007 indicates that the version of LSREX which is linked in
your program is not compatable with the version of Lightspeed on your VS. If you
upgraded Lightspeed on your VS, your application may need to be relinked with a newer
copy of LSREX. See the section “Relinking your application,” below.
MAKING THE CALL: The following example will call LSREX and will run

      01     TEXT-FILE                  PIC X(8) VALUE “MYFILE”.

      01     COMMANDLINE                PIC X(128).
      01     TIMEOUT                    BINARY PIC S9(9) VALUE ZERO.
      01     RESERVED                   BINARY VALUE ZERO.
      01     RETURNCODE                 BINARY.

           “.TXT”        DELIMITED BY SIZE



LINKING YOUR APPLICATION: When you link your application, you must include
LSAPI as one of your link libraries. LSREX uses the system services MSMAP and
MSUNMAP, both in the SSL (Shared Subroutine Library) @SYSSERV. To resolve
these routines, specify YES on the LINK screen. Also specify YES for “Resolve
undefined external symbols interactively” (RESOLVE=YES). This will cause the
LALIASES (Link aliases) screen to be presented. Specify @SYSSERV as ALIAS1.
RELINKING YOUR APPLICATION: LSREX functions by interacting with LSMGR,
and VSBIOS through the shared memory files. If Lightspeed is upgraded, the new
version of Lightspeed may contain a different layout for the shared memory files. This
will cause your application to fail with a LSREX returncode of 1007. If this occurs, you
will need to relink your application with the new version of LSREX in the new LSAPI
library. This does not occur every time Lightspeed is upgraded.


A common use of LSREX is to automate file copies between the VS and PC under VS
program control. The programs VMODE and VCOPY are the Lightspeed utilities that
perform file copies. Lightspeed’s OfficeLink and the Office Import/Export functions are
two examples of using LSREX to automate file copies. Because these commands are
issued so often, all Lightspeed client platforms have been optimized to execute VMODE
and VCOPY commands internally. The typical VMODE commandline is “VCOPY
<sourcefile> <targetfile>.”

The purpose of this white paper is not to document VMODE and VCOPY, these utilities
are already documented at length. Rather several undocumented features have been
added to the internal VCOPY command. Those undocumented features are exposed here:

1) The “[:\” Drive: The drive letter “[:\” always represents the VS mapped drive. The VS
is mapped to the PC using a DOS drive letter. By default, the VS is mapped as the V:\
drive. The command “VCOPY V:\SYSTEM\MYLIB\MYFILE C:\MYFILE.TXT” will
copy the file MYFILE in MYLIB on SYSTEM to the C:\ drive. Any other drive letter
may have been chosen by using the /V=x VATTACH commandline switch. The
command VATTACH /V=E will map the VS as the E:\ drive. Instead of hardcoding the
VS drive letter in LSREX VCOPY commands, “V:\” or “E:\,” for example, use “[:\”
instead. Therefore, the command “VCOPY [:\SYSTEM\MYLIB\MYFILE
C:\MYFILE.TXT” will achieve the same result as the original example. (Note:
LSNVS/32 does not map the VS to a PC drive letter as discussed above. However, the
“[:\” drive mapping still represents the VS. This is the preferred method of copying files.
You can use the new LSNVS/32 LSDOS utility, but LSVT has been optimized to parse
VMODE and VCOPY commands and not LSDOS commands.)

2) The <sourcefile> Dialog: If the sourcefile is a PC file (you are issuing a PC to VS file
copy), you can allow the user to specify the source file in a dialog box by using the “@”
symbol. The command “VCOPY @ [:\SYSTEM\MYLIB\MYFILE” will produce the
following dialog box:
This dialog box will allow the user to peruse their PC to locate the file they wish to copy
to the PC. The file copy will begin as soon as they select a file and press OPEN.

2A) Using a filemask via [M=<mask>]: A mask can be added to show only files that
match the mask. Adding “[M=*.TXT]” in the command “VCOPY @[M=*.TXT]
[:\SYSTEM\MYLIB\MYFILE” will popup a dialog box listing only text files

2B) Changing default drive/directory via [P=<path>]: Before the Open File dialog is
presented, you can specify a default drive and directory by adding “[P=<path>]” to the
<sourcefile> string. The command “VCOPY @[M=*.TXT][P=C:\TMP]
[:\SYSTEM\MYLIB\MYFILE” will present an openfile dialog box showing all *.TXT
files in C:\TMP, and once a file has been selected, the file will be copied to MYFILE in
2C) Specifying a viewer via [V=<app>]: Users may like to view the file they are
selecting before committing to the file copy. The viewer command will specify a PC
application that should be invoked if the user presses “View” (see the dialog box below).
Adding “[V=NOTEPAD]” to the command “VCOPY @[M=*.TXT][V=NOTEPAD]
[:\SYSTEM\MYLIB\MYFILE” will cause a dialog box with only text files listed and a
VIEW button. If VIEW is pressed, the application NOTEPAD will be launched to give
the user the chance to review the file.

2D) Returning the selected file via [F=c,r,l]: Your application may want to obtain the
name of the file that was selected. Adding [F=c,r,l], where ‘c’ and ‘r’ is a column and
row position on the workstation screen where the filename should be placed. ‘l’ is the
length of the field. The command [F=1,1,79] will cause the full filename to be placed in
a 79-byte field beginning at column 1, row 1. To use this mechanism, read the top line of
the workstation and save it’s contents somewhere. Clear out he top line and create a
modifiable FAC in the first position. Write the empty top line. Issue the LSREX
VCOPY command with “@[F=1,1,79]” as the source file (including [M=] or [V=], if you
desire). Unlock the keyboard (by issuing a Write to the screen of just an orderarea with
the unlock keyboard flag set). Then read the screen. The workstation buffer will now
contain the full path of the file that was copied. You can then write back the contents of
the top line that you saved off in the first step.

3) The <targetfile> Dialog: If the targetfile is a PC file (you are issuing a VS to PC file
copy), you can force a dialog box to appear that allows the user to select an output
location by representing the targetfile with an ‘@’ symbol. The command “VCOPY
[:\SYSTEM]MYLIB\MYFILE @” will copy the file MYFILE in MYLIB to the location
specified by the user via the following dialog box:
3A) Providing a default filename via [M=<file>]: You can initialize the dialog with a
default filename by adding [M=<file>] to the targetfile. The command “VCOPY
[:\SYSTEM\MYLIB\MYFILE @[M=XYZ.TXT]” will initialize the filename to
XYZ.TXT (see the example dialog shown above).

3B) Changing default drive/directory via [P=<path>]: Before the Save As dialog is
presented, you can specify a default drive and directory by adding “[P=<path>]” to the
<targetfile> string. The command “VCOPY [:\SYSTEM\MYLIB\MYFILE
@[M=XYZ.TXT][P=C:\TMP]” will present a Save As dialog box with a suggested
filename of XYZ.TXT in C:\TMP.


LSREX typically executes the specified application and waits until that application
completes. The command “NOTEPAD C:\AUTOEXEC.BAT,” for example, will
execute NOTEPAD. Your VS application will not continue until Notepad is closed by
the user (or the timeout, if any, expires). If a command is preceded by “LAUNCH,” as in
“LAUNCH NOTEPAD C:\AUTOEXEC.BAT,” Notepad will be launched and your
application will immediately resume. This is a launch and forget feature; once an
application is launched, you will not be able to obtain the DOS errorlevel produced by
that application. Nor will you be notified when that application is closed.


Shared By: