Runtime (,RT_) Calls

WARNING: These are UNSUPPORTED features used to call operating system functions, and they may be changed or removed at any time. Although these may give you information useful towards fulfilling your needs, APPX Software is not responsible for the maintenance or support of these functions. It is highly recommended that developers use the API's introduced in Release 5.1.

Documentation is provided below on the following OS calls:

  RT_GETENV()
  RT_GETPARAM()
  RT_GET_PROC_NAM()
  RT_SLEEP()

  RT_OPEN_STREAM()
  RT_WRITE_STREAM()
  RT_READ_STREAM()
  RT_CLOSE_STREAM()

________________________________________________________________________

Things to know when reading this document:

Passing data into RT calls:
---------------------------
ubyte * = PASS statement of an alpha field, TYPE=FIELD, Share=Y
uint16* = PASS of a 2 byte numeric/binary, TYPE=FIELD, Share=Y
uint32* = PASS of a 4 byte numeric/binary, TYPE=FIELD, Share=Y
(uint32* can use PDF fields --- AI,BI,CI, etc., which are 4 byte binaries)


Understanding Return values
---------------------------
SUCCESS puts numeric value of +1 into '--- RETURN CODE'.
FAILURE puts numeric value of 0 into '--- RETURN CODE'.
Return(x) puts return value (x) into '--- RETURN CODE'.

/****************************************************************
** NAME: RT_GETENV()
**
** PURPOSE: This function is used to get the value of an environment
** variable using a CALL statement. Put the name of the
** environment variable in the "buf" field, and this function
** will check the OS environment and return the value into
** "buf".
**
** INPUT: ubyte * buf - source/destination buffer
** uint32 * len - length (input and output)
**
** OUTPUT: returns SUCCESS if environment variable is translated, FAILURE
** otherwise.
*/

example:

        TRAP
        SET      --- TEMP 32         =      WINDIR
        SET      --- WORK UINT32     =      32
        PASS     --- TEMP 32         FIELD            SHARE? Y
        PASS     --- WORK UINT32     FIELD            SHARE? Y
        CALL         ,RT_GETENV      RESIDENT? Y  END? N  FAIL 0
        SET      --- TEMP 32         =  --- TEMP 32

In this example, --- TEMP 32 is set to the environment variable you
want to retrieve (in this case APPXPATH).

"--- WORK UINT32" is set to the length of the first field passed
(in this case 32). You can use your own field here, but it has to
be defined as a 4 byte unsigned binary number.

Be user and change 'SHARE' and 'RESIDENT?' from 'N' to 'Y'.

If the CALL is successful, --- TEMP 32 will contain the value of
the PASSed environment variable.

(thanks to Morgan for this example and explanatory text.)


/****************************************************************
** NAME: RT_GETPARAM()
**
** PURPOSE: This function is similar in working style to rt_getenv(), but
** instead of pulling information from the environment, data is
** drawn from the command line. APPX has already stripped out
** the parameters it has used in the BI process (actually parsed
** in SS), so we will only be looking at what is left.
**
** DESCRIPTION:The App. will call rt_getparam() with a string parameter.
** The function will then look for that string on the command
** line (either alone or in the form STRING=VALUE). If it is
** found, in either form, SUCCESS will be returned. The value
** associated with the parameter will then be translated into
** STRING (which originally held the name of the parameter. If
** the parameter is found alone, then blanks will be placed in
** the string. A return value of SUCCESS indicates that the
** parameter was present on the commmand line (and that the
** value of the string is worth taking a look at). A return
** value of FAILURE indicates that the parameter was not found
** on the command line, and the original value of the string
** is maintained.
**
** INPUT: ubyte * buf - source/destination buffer
** uint32 * len - length (input and output)
**
** OUTPUT: returns SUCCESS if string was found, FAILURE otherwise.
*/

/****************************************************************
** NAME: RT_GET_PROC_NAM()
**
** PURPOSE:
** This function will return the Process Name of the
** PARENT process of the current process.
**
** INPUT:
** ubyte * proc_nam - pointer for result
**
** OUTPUT:
** This function will return SUCCESS and the Process Name
** of the current process's parent (if possible), otherwise will return
** FAILURE.
*/

/****************************************************************
** NAME: RT_SLEEP()
**
** PURPOSE:
** This function will allow the App. to tap into the system
** sleep routine. This will cause APPX to stop running (and
** stop taking up CPU time) until a certain number of seconds
** have elapsed.
**
** INPUT:
** uint16 * time - number of seconds to sleep
**
** OUTPUT:
** This rt function will always return SUCCESS.
*/


/****************************************************************
* NAME: RT_OPEN_STREAM()
**
** PURPOSE:
** This function opens a simple stream file using the path, filename,
** and mode provided. It then returns a FILE pointer to be used by
** rt_read_stream, rt_write_stream, & rt_close_stream.
**
** INPUT:
** ubyte * f_name /Path/Filenameof file to open. NULL Terminate
** ubyte * f_mode File Mode to Open as. NULL Terminate
** uint32* f_ptr Empty field to capture file pointer
**
** OUTPUT:
** This function will return SUCCESS, unless APPX has a problem
** opening the requested file.
*/

/****************************************************************
** NAME: RT_WRITE_STREAM()
**
** PURPOSE: This function is used to write a raw text buffer to a standard
** unix file.
**
** INPUT: ubyte * d_buff Data Buffer to write. NULL Terminate
** uint32* f_ptr File pointer to open stream.
**
** OUTPUT: This function returns SUCCESS if the bytes written match the
** number of bytes in the input string..
*/

/****************************************************************
** NAME: RT_READ_STREAM()
**
** PURPOSE: This function is used to read a raw text buffer from a
** standard unix file.
**
** INPUT: ubyte * data_buf Data Buffer to write into the above file
** uint32* max_len Max buffer len of field passed in f_name
** uint32* f_ptr Pointer to open file.
**
** OUTPUT: This function returns SUCCESS if it reads more than 0 bytes.
**
** READ_STREAM does not initialize 'data_buf' before reading
** data from the target file.
**
** An end-of-line delimiter (hex(0a)) will terminate reading in
** the current READ_STREAM invocation, to be started at the
** character thereafter in a subsequent READ_STREAM invocation.
*/

/****************************************************************
** NAME: RT_CLOSE_STREAM()
**
** PURPOSE: This function is used to close a stream file.
**
** INPUT: uint32* f_ptr File pointer.
**
** OUTPUT: returns SUCCESS if the file is successfully closed.
*/

All we did was "wrap" the C function fgets() to get a string from a file.
The fgets() function returns a string value from the characters in the file
up to and including the end-of-line character(s). In unix, this is 0x0A.
In Windows this is 0x0D/0x0A. Strings in C are NULL terminated with a 0x00
value.

So, if you pass in an ALPHA field with all spaces 0x20, and read a value
from a file of "1234", you would wind up with an ALPHA field containing
the following:

0x31 0x32 0x33 0x34 0x0A 0x00 0x20 0x20 0x20 ...

The normal way to locate the end of a C string using APPX ILF is to test
if ALPHA "IN" a NULL and then back up one more character to step over the
end-of-line character, or two if running under Windows.

This is why these are not openly documented or supported. They were
shortcuts to satisfy an immediate need of our or a customer and are not
always the perfect or easy to understand solution for everyone.

Comments:

Read what other users have said about this page or add your own comments.