PCTRun task -- <pct:run />

Description

Executes a Progress procedure.

This task generates a temporary Progress procedure on the fly which sets the propath and declares database aliases according to specified parameters, and then runs the specified procedure.

This temporary procedure is launched by an Exec task, with prowin32 or _progres executable, and with the specified arguments.

The generated procedure follows this template :

// Call this function in your procedures to retrieve parameters
FUNCTION getParameter RETURNS CHARACTER (k AS CHARACTER).
CONNECT VALUE('…') NO-ERROR. // 1 line for each database to connect
CREATE ALIAS '…' FOR DATABASE … [NO-ERROR]. // 1 line for each alias
ASSIGN PROPATH = '…' + PROPATH. // 1 line for each propath entry
RUN VALUE('…') NO-ERROR.
// Check error status, return-value and outputs result to a file
// Quit

Return values

PCT assumes a RETURN-VALUE of 0 is a success. Database connection failure will always returns 14. Error during procedure execution returns 1.

Parameters

Attribute	Description	Type	Requirement	Default value
procedure	Procedure to execute	String	Required	No default value
graphicalMode	True if you want to execute procedure using prowin32, _progres otherwise	Boolean	Optional	False (_progres)
baseDir	The directory in which the Progress runtime should be executed.	File	Optional	Current Ant's directory
failOnError !!NEW!!	Stop the buildprocess if the Progress procedure exits with a return value other than 0.	Boolean	Optional	True
debugPCT	True to keep internal temporary files on disk	Boolean	Optional	False
centuryYearOffset	Century Year Offset (-yy parameter)	Integer	Optional	Progress default
cpInternal	Internal code page (-cpinternal parameter)	String	Optional	undefined
cpStream	Stream code page (-cpstream parameter)	String	Optional	undefined
dirSize	The number of compiled procedure directory entries (-D parameter)	Integer	Optional	Progress default
inputChars	The number of characters allowed in a single statement (-inp parameter)	Integer	Optional	Progress default
maximumMemory	The amount of memory allocated for r-code segments (-mmax parameter)	Integer	Optional	Progress default
parameter	Parameter (-param parameter)	String	Optional	No default value
stackSize	Stack size in 1KB units (-s parameter)	Integer	Optional	Progress default
token	The number of tokens allowed in a 4GL statement (-tok parameter)	Integer	Optional	Progress default
compileUnderscore	COMPILE statement allows underscores (-zn parameter)	Boolean	Optional	False
paramFile	Parameter file (-pf parameter). -pf is always the first argument on the command line.	File	Optional	No default value
iniFile	Use a .ini file (adds -basekey INI -ininame ...)	File	Optional	No default value
TTBufferSize	Buffer Size for Temporary Tables (-Bt attribute)	Integer	Optional	Progress default
MsgBufferSize	Message buffer size (-Mm attribute)	Integer	Optional	Progress default
NumSep	Thousands separator. Can be either a numeric value or a character, e.g. numsep="44" or numsep=","	String	Optional	Progress default
NumDec	Fractional separator. Can be either a numeric value or a character, e.g. numdec="46" or numdec="."	String	Optional	Progress default
DebugReady	Port on which debugger should connect (disabled by default)	String	Optional	No default value
tempDir	Temporary directory for Progress runtime (-T parameter)	File	Optional	Progress config file default
resultProperty !!NEW!!	The name of a property in which the return code of the Progress procedure should be stored. Only of interest if failonerror=false.	String	Optional	No default value

Parameters as nested elements

PCTConnection (com.phenix.pct.PCTConnection)

Adds a database connection on startup

propath (org.apache.tools.types.Path)

Creates a nested propath, and adds it to the implicit propath.

PCTRunOption (com.phenix.pct.PCTRun.PCTRunOption)

Adds an additional command line option to prowin32 or _progres executable. These options are always appended at the end of the standard command line (before -p parameter).

WARNING : an option containing a space will be surrounded by quotes. If a value is needed by a parameter, add it in the value attribute. This is needed if the value contains spaces for example.

Parameter (com.phenix.pct.RunParameter)

Creates a parameter which can be read in the called procedure using DYNAMIC-FUNCTION('getParameter' IN SOURCE-PROCEDURE, INPUT 'ParameterName'). Returned value type is CHARACTER. If parameter is not defined, the function returns ?.

WARNING : these parameters are written in a temp-table without unique index. Defining a parameter with same name multiple times may lead to weird results (it will return ?).

OutputParameter (com.phenix.pct.OutputParameter) !!NEW!!

Adds an character OUTPUT PARAMETER to the called procedure. This value is then written to the specified Ant property.

env

It is possible to specify environment variables to pass to the system command via nested <env> elements.

Attribute	Description	Required
key	The name of the environment variable. Note: (Since Ant 1.7) For Windows, the name is case-insensitive.	Yes
value	The literal value for the environment variable.	Exactly one of these.
path	The value for a PATH like environment variable. You can use ; or : as path separators and Ant will convert it to the platform's local conventions.
file	The value for the environment variable. Will be replaced by the absolute filename of the file by Ant.

Examples

<PCTRun procedure="test.p" dlcHome="${env.DLC}"/>

Commandline : ${env.DLC}/bin/_progres -b -p test.p

---

<PCTRun procedure="test/test.p" dlcHome="${env.DLC}" graphicalMode="true" parameter="foobar"/>

Commandline : ${env.DLC}/bin/prowin32 -b -param foobar -p test/test.p

---

<PCTRun procedure="test/test.p" dlcHome="${env.DLC}" graphicalMode="true" parameter="foobar">
  <PCTConnection dbName="foo" dbDir="base" singleUser="true">
    <PCTAlias name="foo2" />
    <PCTAlias name="foo3" />
  </PCTConnection>
  <propath>
    <pathelement path="src/include" />
    <pathelement path="src/include2" />
  </propath>
  <PCTRunOption name="-cprcodeout" value="utf-8" />
  <Parameter name="Param1" value="Value1" />
  <Parameter name="Param2" value="Value2" />
  <OutputParameter name="FirstParam" />
  <OutputParameter name="SecondParam" />
</PCTRun>

Commandline : ${env.DLC}/bin/prowin32 -b -param foobar -cprcodeout utf-8 -p pctinitxxxx.p

Procedure pctinitxxxx.p will approximately look like that :

DEFINE TEMP-TABLE ttParams NO-UNDO
  FIELD key AS CHARACTER
  FIELD val AS CHARACTER.
FUNCTION getParameter RETURNS CHARACTER (k AS CHARACTER).
  FIND ttParams WHERE ttParams.key EQ k NO-LOCK NO-ERROR.
  RETURN (IF AVAILABLE ttParams THEN ttParams.val ELSE ?).
END FUNCTION.
CONNECT VALUE("-db base/foo -1").
IF ERROR-STATUS:ERROR THEN DO:
  MESSAGE 'Unable to connect to -db base/foo -1'.
  RUN returnValue(14).
  QUIT.
END.
CREATE ALIAS 'foo2' FOR foo.
CREATE ALIAS 'foo3' FOR foo.
ASSIGN PROPATH='src/include2,' + PROPATH.
ASSIGN PROPATH='src/include,' + PROPATH.
DO ON ERROR UNDO, LEAVE:
  CREATE ttParams.
  ASSIGN ttParams.key = "Param1"
         ttParams.val = "Value1".
END.
DO ON ERROR UNDO, LEAVE:
  CREATE ttParams.
  ASSIGN ttParams.key = "Param2"
         ttParams.val = "Value2".
END.
DEFINE VARIABLE outPrm0 AS CHARACTER NO-UNDO.
DEFINE VARIABLE outPrm1 AS CHARACTER NO-UNDO.
RUN VALUE('test/test.p') (OUTPUT outPrm0, OUTPUT outPrm1) NO-ERROR.
RUN writeOutputParam (INPUT outPrm0, INPUT "someTempFile").
RUN writeOutputParam (INPUT outPrm1, INPUT "anotherTempFile").
// Check errors and call returnValue
PROCEDURE returnValue PRIVATE.
  DEFINE INPUT PARAMETER retVal AS INTEGER NO-UNDO.
  OUTPUT TO VALUE('pctresultxxxxx.out').
  PUT UNFORMATTED retVal SKIP.
  OUTPUT CLOSE.
  QUIT.
END PROCEDURE.
PROCEDURE writeOutputParam PRIVATE.
  DEFINE INPUT PARAMETER prm AS CHARACTER NO-UNDO.
  DEFINE INPUT PARAMETER outFile AS CHARACTER NO-UNDO.
  OUTPUT TO VALUE(outFile).
  PUT UNFORMATTED prm SKIP.
  OUTPUT CLOSE.
END PROCEDURE.

After PCTRun task execution, properties FirstParam and SecondParam will be set with the content assigned by test/test.p.