OV_SYSTEM_SERVICE

You are here:

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