OV_SYSTEM_SERVICE

Performs a basic system service.

Note: The user of this Built-In Function is responsible for any impact it has on any application. No warranty of any kind is expressed or implied. Refer to full Disclaimer.

Function No:

991

DLL Required:

U_BIF991.DLL

For use with

Visual LANSA for Windows

YES

Visual LANSA for Linux

NO

LANSA for i

NO

 

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Type of system service required

Pass as one of:

START  Execute another (non-LANSA) application.

START_LANSA  Start another LANSA application executing.

START_UNIQUE  Execute another (non-LANSA) application if not already started.

1

50

 

 

2

A

Opt

Requested Service Argument 1

When Arg 1 is
      Pass this argument as:

START  Name of application (.EXE) to be started.

You may use a fully qualified name (i.e. with path information) or just the .EXE name. If you do not suffix the name with .EXE then the .EXE suffix will be automatically added.

START_LANSA  Name of the LANSA process, process and function or form that is to be started as another independent system process / job. 

Pass this value as either PROC=PPPPPPPPPP, or,

PROC=PPPPPPPPPP FUNC=FFFFFFF, or, FORM=OOOOOOOOOO

only (where PPPPPPPPPP is the process name, FFFFFFF is the function name and OOOOOOOOO is the form name).

Do NOT under any circumstances include any other

X_RUN parameters into this argument (e.g: PART=PPP, DBID=XXXX, etc).

START_UNIQUE  Name of application (.EXE) to be started if it is not already started. This service is only available in MS Windows environments.

You should NOT use a fully qualified name (i.e. with path information), just the .EXE name. If you do not suffix the name with .EXE then the .EXE suffix will be automatically added.

Note: If Arg 1 is START or START_UNIQUE and arg 2 is LCOADM32 or LCOADM32.EXE (ie without the fully qualified path), LCOADM32.EXE will be found in the LANSA\Connect directory.

1

256

 

 

3

A

Opt

Requested Service Argument 2

When Arg 1 is
      Pass this argument as:

START  Parameters to pass to application being started.

START_LANSA  This argument is not required and any value specified will be ignored.

START_UNIQUE  Parameters to pass to the application if it needs to be started.

1

256

 

 

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Opt

Basic Return Code
OK = Completed (normally)
ER = Error occurred.

2

2

 

 

2

N

Opt

Extended Error Code
This is the operating system error code (when available) that may aid you in error handling or error reporting.

 

 

 

 

3

List

Opt

Returned as
OK = Completed normally
ER = Error occurred.
Only returned for certain argument 1 values as follows:

START  Not returned.

START_LANSA  Not returned.

START_UNIQUE  Not returned.

 

 

 

 

 

Example

The following sample RDML function (which can be copied and pasted into the L4W free form function editor) requests that you specify a program (.EXE) name and any parameters to be passed to it. An attempt is then made to start the specified program executing:

FUNCTION OPTIONS(*DIRECT)
DEFINE FIELD(#OV_PGM) TYPE(*CHAR) LENGTH(50) LABEL('Program')
DEFINE FIELD(#OV_PARMS) TYPE(*CHAR) LENGTH(50) LABEL('Parameters') INPUT_ATR(LC)
DEFINE FIELD(#OV_RETC) TYPE(*CHAR) LENGTH(2) LABEL('Return Code')
DEFINE FIELD(#OV_ERRN) TYPE(*DEC) LENGTH(7) DECIMALS(0) LABEL('Error Code')
**********
BEGIN_LOOP
REQUEST FIELDS(#OV_PGM #OV_PARMS (#OV_RETC *OUT) (#OV_ERRN *OUT))
USE BUILTIN(OV_SYSTEM_SERVICE) WITH_ARGS(START #OV_PGM #OV_PARMS) TO_GET(#OV_RETC #OV_ERRN)
IF COND('#OV_RETC = OK')
MESSAGE MSGTXT('Program started')
ELSE
MESSAGE MSGTXT('Error detected when attempting to start program')
ENDIF
END_LOOP

The following sample RDML function requests that you specify up to 100 lines of text. The lines you specify are transferred into a file, and then either the EPM (OS/2) or NOTEPAD (Windows) source line editors are started against the file created:

FUNCTION OPTIONS(*DIRECT)
DEFINE FIELD(#OV_TEMP) TYPE(*CHAR) LENGTH(20) LABEL('Temp File Name') DEFAULT('C:\TEMP.TXT')
DEFINE FIELD(#OV_EDITOR) TYPE(*CHAR) LENGTH(20) LABEL('Editor Name')
IF COND('*CPUTYPE = OS2')
CHANGE FIELD(#OV_EDITOR) TO(EPM)
ELSE
CHANGE FIELD(#OV_EDITOR) TO(NOTEPAD)
ENDIF
DEFINE FIELD(#OV_RETC) TYPE(*CHAR) LENGTH(2) LABEL('Return Code')
DEFINE FIELD(#OV_TEXT) TYPE(*CHAR) LENGTH(70) COLHDG('Text Details')
DEF_LIST NAME(#OV_LISTD) FIELDS(#OV_TEXT)
DEF_LIST NAME(#OV_LISTW) FIELDS(#OV_TEXT) TYPE(*WORKING) ENTRYS(100)
**********
INZ_LIST NAMED(#OV_LISTD) NUM_ENTRYS(100) WITH_MODE(*CHANGE)
MESSAGE MSGTXT('Type in lines of text to be edited')
REQUEST BROWSELIST(#OV_LISTD)
SELECTLIST NAMED(#OV_LISTD) GET_ENTRYS(*NOTNULL)
ADD_ENTRY TO_LIST(#OV_LISTW)
ENDSELECT
USE BUILTIN(TRANSFORM_LIST) WITH_ARGS(#OV_LISTW #OV_TEMP C B Y) TO_GET(#OV_RETC)
USE BUILTIN(OV_SYSTEM_SERVICE) WITH_ARGS(START #OV_EDITOR #OV_TEMP)

The following sample RDML function requests that you specify a program (.EXE) name and any parameters to be passed to it. An attempt is then made to start the specified program executing. You may start the application by using the START or the START_UNIQUE option .... thus allowing you to see the differences between these options when starting a program that is already active:

FUNCTION OPTIONS(*DIRECT)
DEFINE FIELD(#OV_PGM) TYPE(*CHAR) LENGTH(50) LABEL('Program') DEFAULT('NOTEPAD.EXE')
DEFINE FIELD(#OV_PARMS) TYPE(*CHAR) LENGTH(50) LABEL('Parameters') INPUT_ATR(LC)
DEFINE FIELD(#OV_RETC) TYPE(*CHAR) LENGTH(2) LABEL('Return Code')
DEFINE FIELD(#OV_ERRN) TYPE(*DEC) LENGTH(7) DECIMALS(0) LABEL('Error Code')
DEFINE FIELD(#OV_REQUST) TYPE(*CHAR) LENGTH(20) LABEL('Start Type') DEFAULT(START_UNIQUE)
**********
BEGIN_LOOP
REQUEST FIELDS(#OV_REQUST #OV_PGM #OV_PARMS (#OV_RETC *OUT) (#OV_ERRN *OUT))
BEGINCHECK
VALUECHECK FIELD(#OV_REQUST) WITH_LIST(START START_UNIQUE) MSGTXT('Request value must be START or START_UNIQUE')
ENDCHECK
USE BUILTIN(OV_SYSTEM_SERVICE) WITH_ARGS(#OV_REQUST #OV_PGM #OV_PARMS) TO_GET(#OV_RETC #OV_ERRN)
IF COND('#OV_RETC = OK')
MESSAGE MSGTXT('Program started or it is already started')
ELSE
MESSAGE MSGTXT('Error detected when attempting to start program')
ENDIF
END_LOOP